Key Bridge Web Services
Getting Started Guide

Key Bridge Web Services provide web and data services to power your White Space devices and spectrum-aware applications and software.

Getting started has never been easier.

Overview & Background

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.

Access via HTTP(S) REST

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.

Data Format & Encoding

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.

  • as XML: Content-Type: application/xml
  • as JSON: Content-Type: application/json
  • as XML: Accept-Encoding: application/xml
  • as JSON: Accept-Encoding: application/json

Developer note
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.

Developer note
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.

Quotas & Rate Limits

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.

API Keys

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

Create an Account

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).

Create an API Key

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.

Use an API Key

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.

Configuring OAuth Authentication

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.

Web Service Response Codes

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.

Web Service Troubleshooting

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.

UTF-8 Character Set

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.

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

Back to top