When your application is configured to use Auth Token authentication, it will use the familiar HTTP Bearer token scheme:

• request a new auth token for your client application from the Sila API; this auth token will have a token value and an expiration timestamp. A new auth token will expire in 8 hours.
• store this auth token in your local database, and continue to re-use this token for application-level authorization for all requests until it's nearly expired.

If and when you notice that the token's expiration time is almost up (30 minutes or less), you may request a new auth token from the Sila API. Use of an expired token will return a 401 response.

Requesting an Auth Token

When your client application is first created, it will have two attributes that are used as user and password credentials when requesting an auth token:

• client_id
• client_secret

Requesting an auth token is accomplished by calling the /auth_token endpoint using HTTP Basic Authentication, where client_id corresponds to the username portion of the Basic credentials, and the client_secret corresponds to the password portion. See the /auth_token documentation for the detailed example of the Basic authentication usage.

The return response will include a token that has an 8-hour expiration window. You may re-use this token until it is expired. Use of an expired token will return a 401 response.

Auth Token requests will be rate-limited

Since rate limiting will be implemented on the /auth_token endpoint, you should implement caching the token on your end, and continue using the same token until its expiration time is less than 30 minutes. Requesting another token at this time will return a new token with a full 8-hour expiration window.

No benefit to repeatedly requesting an Auth Token

As described in the documentation for the /auth_token endpoint, if you re-request a token for your client app while your current token has more than 30 minutes left before it expires, the API will return the same token from the previous request to the /auth_token. Only when your token has less than 30 minutes left will a new token with a full 8-hour window be issued.

Caching an Auth Token

The auth token returned from /auth_token will have 3 attributes:

• token string: a alpha-numeric that will be passed back as the base64-encoded token value in a Bearer token authorization header.
• expiration int: an epoch timestamp designating the expiration in the UTC timezone.
• expiration_dt string: a human-friendly date/time representation of the expiration timestamp, conforms to ISO 8601 date and time format in UTC.

Using the Cached Auth Token

You should cache or store the auth token object in your database. When building a request to send to the Sila API, check the expiration time of the token and if it's expired, first request a new token via /auth_token, cache the token returned by that endpoint, then build the Bearer <base64-encoded-token> string from the new auth_token.token value.