Auth Token Management (BETA)
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 anexpiration
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-encodedtoken
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.
Updated 9 months ago