Authorization API
Virtually all calls to OpenTech IoE APIs require an authorized client. This section will walk you through the authorization process via the Authorization API.
API Routes and Documentation
The Authorization service name is “auth”, which can be substituted into the route prefix format of the selected environment (e.g. https://auth.insomniaccia.com ). The Swagger documentation can be found by appending “/swagger” to the route prefix (e.g. https://auth.insomniaccia.com/swagger ). For the purposes of acquiring an access token, you will only be concerned with the /auth/token route. Like all OpenTech IoE APIs, service routes are available for checking the availability and health of the service.
JWT Access Tokens
The Authorization service issues JWT access tokens which are used in all of your calls to the Access Control API. JWTs are easily decoded, but are signed and verified by the Authorization service which prevents tampering. For more information about JWTs, please visit https://jwt.io/ .
Acquire Access Token
To acquire an access token, a POST request must be made to the /auth/token path. The content type of the request must be application/x-www-form-urlencoded. The following parameters are required:
Example CURL
curl https://auth.<route_format>/auth/token
-d "grant_type=password&username=0q..I=&password=Et..A=&client_id=my-application&client_secret=JL..hP"
If the token request is successful, you will receive a 200 response from the service, along with a JSON body containing the following values.
{
"resource": "<Allowed Resources>",
"token_type": "Bearer",
"access_token": "<JWT access token>",
"expires_in": 3600
}
Capture the access token and use it on all authenticated API calls. The “expires_in” field tells you the number of minutes before the token expires, though this value is typically configured for one hour.
If you receive a 400 response, this means your request could not be granted due to several factors: the client credentials are incorrect, the account credentials are incorrect, the application is disabled, the application integration is disabled, or the account is disabled. Please contact the STC Administrators for help in troubleshooting integrations.
Refresh Access Token
Access tokens expire after one hour by default. It is best practice to continue using the same access token until it has expired rather than seeking a new access token for each request. Before your token expires, you should consider requesting a new token using the previous mechanism. Caching the access token for a period of time slightly shorter than the expiration time is an excellent way of implementing this strategy.
Alternatively, you can implement a retry mechanism where you acquire a new token after encountering a 401 error from the Access Control or Access Event API and then retry your original request.