# Auth Endpoint

The Auth endpoint is for authenticating users before they are cleared for placing bets. As per the 'Session Endpoint' section, a temporary (short expiry) token should be made available to the frontend. The frontend will pass this temporary token and the userId to BetLink's auth pathway, which ultimately calls this Auth endpoint. This token is named 'launchToken' in the request parameters section below.

This Auth endpoint must return a backend authentication token that will be used subsequently by BetLink for bet placement requests.

Behind the scenes, the operator may implement the functionality as they see fit but there are some strong recommendations:

* The operator should validate that there is indeed a valid user session for the relevant user. The user session is valid for auth if there exists a non-expired temporary token and no auth token has been generated yet for this user session.
* A random auth token should be generated and stored along with the pre-existing user session. This token is the operatorSessionToken in the response parameters section below.
* An expiry date for the above auth token should be set and stored along with the pre-existing user session (recommended 30 minutes).

### Request Parameters

type: `POST`\
content-type: `application/json`

#### Idempotency

Request will contain a header `X-Idempotency-Key` in the form of a UUID string. See 'Idempotency' section for more information.

<table><thead><tr><th>Parameter</th><th width="181">Type</th><th width="112">Required?</th><th>Example</th></tr></thead><tbody><tr><td>requestId</td><td>String/UUID</td><td>Yes</td><td>92e02ae9-a2a3-48e2-af0e-940aec4bbcfb</td></tr><tr><td>userId</td><td>String</td><td>Yes</td><td>user123</td></tr><tr><td>operatorId</td><td>String</td><td>Yes</td><td>operator-id</td></tr><tr><td>launchToken</td><td>String</td><td>Yes</td><td>6rI4bf7ghCfk43uyeYJ4Pg</td></tr><tr><td>authRequestedTimestamp</td><td>String (epoch)</td><td>Yes</td><td>1640995200000</td></tr></tbody></table>

### Success Response Parameters

accepts: `application/json`

<table><thead><tr><th>Parameter</th><th width="181">Type</th><th width="116">Required?</th><th>Example</th></tr></thead><tbody><tr><td>requestId</td><td>String/UUID</td><td>Yes</td><td>Matches request's requestId</td></tr><tr><td>userId</td><td>String</td><td>Yes</td><td>user123</td></tr><tr><td>operatorId</td><td>String</td><td>Yes</td><td>Matches requests OperatorId</td></tr><tr><td>operatorSessionToken</td><td>String</td><td>Yes</td><td>Original or refreshed</td></tr><tr><td>timestamp</td><td>String (epoch)</td><td>Yes</td><td>1640995200000</td></tr><tr><td>status</td><td>String (enum)</td><td>Yes</td><td>AUTHENTICATED</td></tr><tr><td>sessionExpiry</td><td>String (epoch)</td><td>Yes</td><td>1640995200000</td></tr><tr><td>redirectUrl</td><td>String</td><td>Yes</td><td>https://imgarena.com (Please return your homepage url)</td></tr></tbody></table>

### Error Response Parameters

accepts: `application/json`

<table><thead><tr><th>Parameter</th><th width="181">Type</th><th width="112">Required?</th><th width="143">Example</th><th>Notes</th></tr></thead><tbody><tr><td>status</td><td>String ("FAILED_AUTHENTICATION")</td><td>Yes</td><td>FAILED_AUTHENTICATION</td><td>Always this value</td></tr><tr><td>errorCode</td><td>String (enum)</td><td>Yes</td><td>INVALID_SESSION</td><td>Must be an Error Code from the Errors table below</td></tr><tr><td>errorMessage</td><td>String</td><td>Yes</td><td>User has not passed validation checks</td><td>Can be any debug information operator wishes to respond with</td></tr></tbody></table>

#### Errors

| Error Code             | Http Status |
| ---------------------- | ----------- |
| INVALID\_USER          | 400         |
| USER\_BLOCKED          | 400         |
| MISSING\_PARAMETER     | 400         |
| INVALID\_SESSION       | 401         |
| AUTHENTICATION\_FAILED | 403         |
| GENERAL\_EXCEPTION     | 500         |
| REQUEST\_TIMED\_OUT    | 503         |