Key Bridge Web Services and developer software provide easy access many of the core primitives of the Key Bridge White Space System including registrations, device information, user account interfaces and more.

If you're building an application that leverages core White Space System features then this is the API for you.

Key Bridge Web Services are actually multiple APIs operating on an array of servers and accessing various back-end databases. Each API interface is developed and presented according to a common access template and accessed through a standardized REST interface. Most application developers mix and match components within multiple APIs to produce their application.

All services are authenticated through a common credential system. Access entitlements are granted via OAuth security credentials. Some API interfaces are generally available while others require special access privileges. Review the documentation of each service to identify any access or entitlement requirements.

The acronym "API" stands for "Application Programming Interface". An API is a defined way for a program to accomplish a task, usually by retrieving or modifying data. We provide a API methods for most features you can see on our White Space Portal. Programmers may use the Key Bridge API to make applications, web sites, widgets, and other projects that interact with Key Bridge or that provide spectrum-related functionality. Programs talk to the API over HTTP, the same protocol that your browser uses to visit and interact with web pages.

Basic principles of all Key Bridge Web Services are:

REST

Access is via HTTP(S) REST

OAuth

Authentication is via 2-legged OAuth

XML & JSON

All complex data is encoded as XML (default) or JSON

Refer to each service's specific documentation for service-specific data access, authentication, format & encoding details.

All Key Bridge Web Services are accessed via HTTP or HTTPS REST transactions. REST stands for Representational State Transfer and relies on stateless, client-server, cache-able transactions using the HTTP or HTTPS protocol. REST is an architecture style for designing networked applications where simple HTTP messaging is used to make calls between machines rather than complex mechanisms such as CORBA, RPC or SOAP.

"RESTful" applications use HTTP transactions to read data (e.g., make queries), write data (e.g. create and/or update), and to delete data. REST uses standard HTTP transactions for all four standard CRUD (Create/Read/Update/Delete) operations.

All services optionally support HTTPS, while some require HTTPS and do not support HTTP. Refer to each service's documentation for details.

Key Bridge Web Services employ one or more of the following HTTP request methods. Check service documentation for more details.

OPTIONS

Retrieve information from the server describing which communication options are available.

GET

Retrieve information from the server. Query parameters may be encoded in the HTTP request.

POST

Submit an update to the server. This is typically used to update an existing database record.

PUT

Send new information to the server. This typically used to create a new database record.

PATCH

Not used.

DELETE

Delete information on the server. This is typically used to delete a database record.

Key Bridge Web Services read and write data encoded as XML or JSON, according to the user's configuration. API services are flexible in this regard, and can mix an match encoding schemes. For example, a query and response may use different encoding strategies if desired.

Complex data encoding may be specified by the client by adding a Content-Type field to the HTTP header. XML is the default context type and is used if no encoding type is otherwise specified.

Parameter encoding is important. All Key Bridge Web Services require that queries to use the UTF-8 character set and will always respond using the UTF-8 character set. See the troubleshooting section for details.

Collection indexing starts at zero. When iterating through an extended response remember that the index parameter always starts at 0, not 1. Starting an index at 1 will skip the first entry in a response collection.

Simple Data

Some services provide simple responses for which object encoding would not enhance or otherwise benefit the service. Simple responses are directly provided with the response type text/plain.

Customer API credentials have no quota or rate limit..

Non-customer access to Key Bridge web services may by capped or rate limited at our discretion. This is implemented by limited the number of messages sent to your client based upon volume per period of time. There are typically two rate limits that may be imposed:

1. A limit on the number of requests per minute. This is to manage the immediate impact of a single client program that is possibly misconfigured or operating contrary to our acceptable use policy.
2. A limit on the number of requests per month. This is to manage the long-term impact and scaling requirements that client applications place upon our compute and storage infrastructure.

All Key Bridge Web Services employ the 2-legged OAuth authentication scheme.

To create an API Key you must first create a system account, which is managed by the keybridge:AM Access Manager system.

Select the New account menu item, enter your email address and a selected password, then follow the account validation process. This will establish your individual sign-in credentials (username and password) that you will use to create and manage your API key(s).

Select the New API key menu item on the keybridge:AM Access Manager system. If you have not already done so you will be asked to sign in.

Enter a short name for your application ("My First Application" for example) and optionally a brief description. Leave the operating environment as Development. Don't worry if you make a mistake - you can edit everything later.

Key Bridge Web Services authenticate via 2-legged OAuth. Although there is an official spec for OAuth 1.0, the spec only outlines the standard "3-legged OAuth". An alternative form, loosely referred to as "2-legged OAuth", enables secure machine-to-machine communication via a certificate (e.g. username) and pre-shared keys (e.g. password).

2-legged OAuth is a term that is a variant of OAuth which does not require users to authenticate through a third-party system. The vast majority of automated REST API calls made on the Internet using OAuth are made using 2-legged OAuth and allow a device or software to securely and automatically communicate with a home server.

Key Bridge Web Services access credentials do not have an explicit expiration and will be valid for use when making requests for as long as your use does not violate our acceptable use policy.

Your keybridge:AM issued API key contains two fields: a Consumer Key and and Shared Secret. Most OAuth clients and software frameworks provide simple configuration interfaces to enter these configuration parameters.

Configure your 2-legged OAuth client as follows:

Request Signature Configuration

Field	Description
Consumer key	Enter the Consumer Key value exactly as provided. It's typically easiest and least error-prone to copy and paste directly. Be sure to not add any spaces!
Consumer secret	Enter the Shared Secret value exactly as provided. It's typically easiest and least error-prone to copy and paste directly. Be sure to not add any spaces!
Access token	Leave blank. This is not used.
Access token secret	Leave blank. This is not used.

OAuth Settings Configuration

Field	Description
Signature Methods	HMAC-SHA1
OAuth Version	1.0
Realm	Leave blank. This is not used. If required by the client select Auto and/or Disabled.
OAuth Nonce	Leave blank. This is automatically calculated by the client. If required select Auto.
OAuth Timestamp	Leave blank. This is automatically provided by the client. If required select Auto.

Key Bridge Web Services attempt to return appropriate HTTP status codes for every request. In addition, a descriptive error text or error message may also be provided in the response header. The following table describes the codes which typically appear when working with the API:

Code	Text	Description
200	OK	Success!
400	Bad Request	The request was invalid. If possible an accompanying error message in the header will explain the nature of the error encountered. This status code is typically returned when a required parameter is missing or incorrectly configured.
401	Unauthorized	Authentication credentials were missing or incorrect or the request was submitted via HTTP for a service where HTTPS is required.
403	Forbidden	The request is understood, but it has been refused or access is not allowed. If possible an accompanying error message in the header will explain why. This code is used when requests are being denied due to over quota or insufficient access privileges.
404	Not Found	The URI requested is invalid or the requested resource, such as database record, does not exists. If possible an accompanying error message in the header will provide additional information. This code is also returned when the requested format is not supported by the requested method.
429	Too Many Requests	Returned when a request cannot be served due to the application's rate limit having been exhausted for the resource.
500	Internal Server Error	Something is broken. Please file a bug report if you see this message so our team can investigate.
502	Bad Gateway	The service is not available or being upgraded.
503	Unavailable / Maintenance	The system is operating but the specific service is either under maintenance or overloaded with requests. See the service main page for more information and please try again later.
504	Gateway timeout	The system is operating but the request could not be handled due to a networking failure or misconfiguration. Please try again later.

If you are receiving a status code 403: Forbidden response then your account does not have sufficient privileges for the resource you are trying to access. Contact us to ensure your API credentials are assigned their correct entitlements.

If you are receiving a status code 401: Unauthorized response then please check the following:

HTTPS

Are you using HTTPS?

Some web service requests must be submitted via HTTPS and not HTTP. Confirm access requirements with the API's documentation.

Consumer Key

Did you use your public key for a consumer key?

Key Bridge OAuth Consumer keys are formatted as 5 hyphen-separated text fields, as shown in this example: 0724578a-5e7e-11e2-921c-0024211c6fd1.

Shared Secret

Did you copy the entire shared secret correctly?

The shared secret is a 64-character word and we recommend you copy and paste this sequence instead of transcribing it.

Character Set

Are you submitting or receiving non-standard characters? See below.

If you are receiving a status code 400: Bad Request, 414: Request-URI Too Long, or 500: Server Error either intermittently or for requests that should normally work you may be using an incorrect character set.

Most software uses the system character set by default, which may be US-ASCII, LATIN, etc. To maximize interoperability all Key Bridge Web Services use and require the the UTF-8 character set when transmitting or receiving non-standard or international characters.

To specify UTF-8 query encoding:

• as XML: Content-Type: application/xml;charset=utf-8
• as JSON: Content-Type: application/json;charset=utf-8

To specify UTF-8 reply encoding:

• as XML: Accept-Encoding: application/xml;charset=utf-8
• as JSON: Accept-Encoding: application/json;charset=utf-8