Authentication

aWhere leverages OAuth2 to control access to the API. With this approach, you'll generate an access token which is then used with all your API requests. For reference, these APIs use the OAuth2 Client Credentials grant workflow.

API Keys

All applications will be issued their own API Key and Secret. Follow the Get Started page or visit My Apps to create or retrieve your credentials. The next section describes how to use them to get a token. All access restrictions and rate limits are regulated by your key.

Important: You must secure the API Secret (and you should secure the Key as well). If your credentials ever become known outside your authorized systems, your account may be compromised. Compromised keys will be immediately terminated. Never attempt to generate a token from browser-executed JavaScript, as browser-side JavaScript is inherently insecure.

Best Practice: Every distinct application you build should have its own Key and Secret, don't share them between applications. Sharing keys can inadvertently trip the quota limit and limit your app's ability to use the APIs. If you are building a mobile application for distribution to many users, contact us for a special configuration.

Generating a Token

You will use your keys to generate an access token. The token is what is sent with regular API calls to authorize your use.

API Endpoint

You will send a POST request to the following endpoint:

https://api.awhere.com/oauth/token

HTTP Headers

Include the following HTTP Headers with your request:

Content-Type: application/x-www-form-urlencoded
Authorization: Basic {hashed_credential}

You will need to replace {hashed_credential} with the Base64-encoded {key}:{secret} combination, separated by a colon.

Example: If your API Key is ABCDEFG and your Secret is 123456, you would Base-64 encode ABCDEFG:123456 which is equal to QUJDREVGRzoxMjM0NTY=.

Request Body

Lastly, be sure to include the following text in the request body:

grant_type=client_credentials

Response

The Token API will return a payload containing two properties, one with your access token, and the other with the number of seconds until the token expires. Save the token to a variable or to memory for use with regular API calls. For example:

{
    "access_token": "3RP1EJmaQI2h4GSSD",
    "expires_in":3599
}

Using a Token

All regular API requests require the token be sent in the Authorization HTTP Header like so:

Authorization: Bearer {token}

For example, if retrieving a list of available models, the HTTP request would be:

GET /v1/models
Authorization: Bearer 3RP1EJmaQI2h4GSSD

Token Expiration

Tokens expire after an hour. Once a token is expired, you'll receive the HTTP Status Code of 401 Unauthorized. Simply request a new token following the explanation above. There is no limit to the number of tokens you can request and tokens can overlap—so alternatively, your code can include a timer mechanism to request a new token before the current one expires.