Resistant Documents API (2.0.0b)

Brief introduction to OAuth2

OAuth2 is an authorization protocol designed to allow applications to access resources on behalf of a user without sharing the user's credentials. It's widely used for web, mobile, and desktop applications, providing a standardized way to manage access to APIs and user data.

How it works

1. The client (application) is registered with the authorization server to obtain a client ID and client secret. (Service access provisioning)
2. The client requests the authorization server to grant access to desired resources and provides Access token.
3. The client can access desired resources until Access token expires ( e.g. 15 minutes). Expiration datetime (exp as Unix Timestamp ) is accessible in the token payload together with issue datetime (iat). Any library for work with JWT should support this functionality, e.g. PyJWT (python).

{
  ...
  "iat": 1742473136,
  "exp": 1742474036,
  ...
}

Differences to other authn techniques e.g. API Key

• OAuth Access Token provides an enhanced security as tokens are short lived and revocable, reducing a risk of credentials exposure.
• Access Token should be re-used across multiple requests till token is expired (based on token expiration date time e.g. 15 minutes).
• Authorization Server Token endpoint is protected resource that can issue only finite number of tokens.

Implementation details

The standard client credentials flow:

1. Client makes a request to authorization server using client credentials

BASIC_AUTH=$(echo -n $CLIENT_ID:$CLIENT_SECRET | base64)
curl --request POST \
  --url 'https://eu.id.resistant.ai/oauth2/aus2un1hkrKhPjir4417/v1/token' \
  --header 'accept: application/json' \
  --header "authorization: Basic $BASIC_AUTH" \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=submissions.read submissions.write'

2. If the credentials are valid, authorization server responds with an access token

{
  "access_token": "eyJhbG[...]1LQ",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "submissions.read submissions.write"
}

3. Client uses the access token to make subsequent API requests with Authorization header

Authorization: Bearer eyJhbG[...]1LQ

Please note that Token URL is specific for a given environment. Correct URL is in the corresponding environment documentation.