Auth API

Getting Started

First things first, to be able to push any data to our platform you need to have a username and password combination. In case you don’t have these yet, get in touch with our support team at support@simacan.com; with the credentials supplied you can communicate with our Auth API to request your access tokens.

Context

All of our APIs work with OAuth 2.0 with JSON Web Tokens, which is an industry-standard for authorization. You might have seen this with other APIs you currently work with. See JSON Web Tokens for OAuth 2.0 and JWT.IO for more in-depth information. Before you can communicate with our APIs, you need to obtain an access token first. Underneath you can find a graphical representation of the flow. Let’s get started!

UserAuth APITarget APIUser CredentialsAccess + Refresh TokensToken valid 1 hourTarget Request + Access TokenTarget Response dataUserAuth APITarget API

Environment

In general the URI of a production service looks like: https://*.services.simacan.com. For staging environments they are suffixed with -stg like this: https://*-stg.services.simacan.com. You will receive separate credentials for staging and production environments.

For the Auth API we use the following URIs:

  • Production URL : https://auth-service.services.simacan.com/api/v1
  • Staging URL : https://auth-service-stg.services.simacan.com/api/v1
  • Endpoint: /auth/password (Getting an access token)
  • Endpoint: /auth/refresh (Refresh a refresh token)

Example

Getting an access token

As stated above, under “Getting Started”, please make sure you have your username and password ready. You need to make a POST request, with content-type application/x-www-form-urlencoded containing your username and password in the body. See the snippet below.

Send it

In this example, you should replace <yourUsername> and <yourPassword> by your own credentials. Here we post to the staging URL.

Unix/MacOSWindows
Copy
Copied
curl -X POST https://auth-service-stg.services.simacan.com/api/v1/auth/password -H "content-type: application/x-www-form-urlencoded" -d "username=<yourUsername>&password=<yourPassword>"
Copy
Copied
curl.exe -X POST https://auth-service-stg.services.simacan.com/api/v1/auth/password -H "content-type: application/x-www-form-urlencoded" -d "username=<yourUsername>&password=<yourPassword>"

Response

Your response should look like the following, just with way longer token values. Congratulations, you have your tokens.

Copy
Copied
{
    "access_token": "eyxxxxxxxxxxxxxx",
    "refresh_token": "eyxxxxxxxxxxxxx",
    "token_type": "bearer",
    "expires_in": 3600
}
Important: token expiration

Your access_token is of type Bearer. You need to send it to our APIs by an Authorization header, with value Bearer <yourAccessToken> (where of course you replace <yourAccessToken> with your personal access_token). The token's expiry time can be found as value for the expires_in key, which in this case is 3600 seconds or 1 hour.

info

In rare cases the token can expire earlier than the value set for expires_in; when this occurs we will start sending 401 responses. Make sure your system is resilient for this. As soon as our services start returning 401s, your system should try refreshing the token.

Refreshing your token

Once our APIs are sending you 401 responses, your authorization is expired. Next, you should refresh your token. The correct way to do this is: send us the refresh_token that we sent you earlier and as a result, we will grant you access again for 1 hour, and we will send you a newer refresh_token. You should discard the old one.

UserAuth APITarget APIUser CredentialsAccess + Refresh TokensYou waited longer than 1 hourTarget Request + Access Token401 UnauthorizedRefresh TokenAccess + Refresh TokensTarget Request + Access TokenTarget Response dataUserAuth APITarget API
warning

Please prevent your system from repeatedly sending your username and password to the /auth/password endpoint for this, as this is considered an unsafe action. The only reason to use /password again is if the refresh token itself expires. This can happen in very rare cases and can be recognized by the /refresh endpoint returning a 401. It is recommended to have a fallback to the /password call just to be resilient against this.

Send it

In this example you should replace <yourRefreshToken> by your own token.

Unix/MacOSWindows
Copy
Copied
curl -X POST https://auth-service-stg.services.simacan.com/api/v1/auth/refresh -H "content-type: application/x-www-form-urlencoded" -d "refresh_token=<yourRefreshToken>"
Copy
Copied
curl.exe -X POST https://auth-service-stg.services.simacan.com/api/v1/auth/refresh -H "content-type: application/x-www-form-urlencoded" -d "refresh_token=<yourRefreshToken>"

Response

Your response should contain a new refresh_token. After 1 hour, you will have to repeat the above process. Don’t keep any old refresh_tokens.