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.

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.

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.

To specify the query encoding:

as XML: Content-Type: application/xml

as JSON: Content-Type: application/json

To specify the reply encoding:

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:

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.

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

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.

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.

Request Signature Configuration

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.

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.