Skip to content

Authentication & Security

In this chapter, we introduce the API-independent authentication and security concepts.

Authentication

Our APIs use bearer token authentication. The general flow looks like this:

%%{init: {'theme': 'dark'}}%%
sequenceDiagram
    participant Client
    participant Auth as Token Endpoint
    participant API as API Endpoint

    rect rgba(40, 44, 52, 0.6)
        Note over Client, Auth: Token Acquisition
        Client->>Auth: POST /token {username, password}
        Auth-->>Client: Return Bearer Token
    end

    rect rgba(40, 44, 52, 0.6)
        Note over Client, API: Using Token for API Access
        Client->>API: Request with Authorization: Bearer {token}
        API-->>Client: Response data
    end

You must acquire a token and use it to authenticate your requests. The token is valid for 24 hours and must be used to authenticate all subsequent operations. To obtain a token, you need to authenticate using a token endpoint. We provide two possible methods:

Most of our APIs provide a token endpoint to fetch a token. 

POST https://<api-name>.REGION.ENV.savr.saveris.net/token

Include the following JSON in the body of the request to provide your username and password:

{
   "username": "string",
   "password": "string"
}

Note

The Push API, being a WebSocket API, does not provide a token endpoint. However, you can use one of the other token endpoints to get the token or use the second method. For example, refer to the Data API

2. Get a token directly over Cognito

Follow these steps to authenticate and obtain an ID token:

  1. Send a POST request to https://cognito-idp.eu-central-1.amazonaws.com/ with headers:
  2. X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
  3. Content-Type: application/x-amz-json-1.1

  4. Request body: 

    {
   "AuthParameters" : {
      "USERNAME" : "example-user",
      "PASSWORD" : "your-password"
   },
   "AuthFlow" : "USER_PASSWORD_AUTH",
   "ClientId" : "your-client-id"
}

  5. The response will contain a JSON object with an IdToken field.

For more detailed information about the API endpoints, please refer to the API references of each API.

What Next?

We recommend continuing with the general concepts chapter if you are not familiar with this.