# 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](mailto: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](https://oauth.net/2/jwt/)
and [JWT.IO](https://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!


```mermaid
sequenceDiagram
	User->>+Auth API: User Credentials
	Auth API->>+User: Access + Refresh Tokens
  Note right of Auth API: Token valid 1 hour
	User->>+Target API: Target Request + Access Token
  Target API->>+User: Target Response data
```

## 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/MacOS

```shell
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>"
```

Windows

```shell
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.


```json
{
    "access_token": "eyxxxxxxxxxxxxxx",
    "refresh_token": "eyxxxxxxxxxxxxx",
    "id_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.

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.


```mermaid
sequenceDiagram
	User->>+Auth API: User Credentials
	Auth API->>+User: Access + Refresh Tokens
	  Note right of Auth API: You waited longer than 1 hour
	User->>+Target API: Target Request + Access Token
  Target API-->>+User: 401 Unauthorized
  	User->>+Auth API: Refresh Token
	Auth API->>+User: Access + Refresh Tokens
	User->>+Target API: Target Request + Access Token
  Target API->>+User: Target Response data
```

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/MacOS

```shell
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>"
```

Windows

```shell
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.