Skip to content
Riversoft STCP DirectLink API
Authentication
OAuth tokens

OAuth tokens

The POST /auth/token and POST /oauth2/token endpoints are equivalent: they accept the same application/x-www-form-urlencoded form and return the same response. They support two grants:

Grantgrant_typeWhen to use
Password grantpasswordThe integration knows the user and password.
Token exchangeurn:ietf:params:oauth:grant-type:token-exchangeThe integration already has a JWT issued by a provider that the environment accepts.

Note

Token exchange follows OAuth 2.0 and OAuth 2.1. The password grant is part of OAuth 2.0, but not of OAuth 2.1, and may be disabled in the environment. To follow OAuth 2.1, ask the service administrator to disable the password grant in the API authentication methods and use token exchange or Single Sign-On. See OAuth 2.1 compatibility.

Password grant 

read -r -p 'User: ' API_USER
read -r -s -p 'Password: ' API_PASSWORD; printf '\n'

curl -i \
  --data-urlencode 'grant_type=password' \
  --data-urlencode "username=$API_USER" \
  --data-urlencode "password=$API_PASSWORD" \
  "$API_BASE/oauth2/token"

In addition to validating the password, the password grant applies the environment access rules to the user.

Token exchange

Token exchange trades a source JWT for an API access token. The only accepted subject_token_type is urn:ietf:params:oauth:token-type:jwt.

You must also specify which provider configured in the environment validates the JWT. There are two ways:

read -r -s -p 'Source JWT: ' SUBJECT_TOKEN; printf '\n'

curl -i \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data-urlencode "subject_token=$SUBJECT_TOKEN" \
  --data-urlencode 'provider=jwt-provider' \
  "$API_BASE/auth/token"

Provider rules:

  • the value is the identifier of the provider registered by the administrator, and it does not need to match the JWT iss claim;
  • if you send both the provider field and the header, the provider field takes precedence;
  • the X-STCPDIRECTLINK-JWT-ISSUER header is used only in token exchange and does not authenticate protected routes.

Impersonation token

Technical integrations that need a long-lived credential can use an impersonation token instead of obtaining a token on every run.

  • The token is generated by the environment administrator in the Riversoft® STCP DirectLink supervision interface, for a technical user.
  • It carries a session identifier registered for the user. On every call, the API checks this identifier; when the token is replaced, the previous one is no longer accepted.
  • Use it as a Bearer token on protected routes: Authorization: Bearer <token>.

Warning

Treat the impersonation token as a privileged credential: keep it in a secrets vault, record its owner, validity and scope, define its rotation and do not reuse it across environments. It does not replace interactive sign-in.

Response

Both grants return the same format, with Cache-Control: no-store:

{
  "access_token": "<token>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "https://api.example.com/directlink/v2"
}
FieldDescription
access_tokenToken to send in the Authorization: Bearer header of protected routes.
issued_token_typeType of the issued token: OAuth access token.
token_typeHow the token is presented: Bearer.
expires_inToken validity, in seconds. It depends on the environment configuration; 3600 is only an example.
scopeURI of the API configured in the environment. It does not represent a list of permissions.

Use the token as shown in Session and logout.

Errors

When the grant or the source token is not accepted, the API responds 400 with a body in OAuth format:

{
  "error": 400,
  "error_description": "<reason>",
  "error_uri": "<api-uri>"
}

The error field is numeric and identifies the condition reported by the validation. See Codes and events.

Local login and MFASingle Sign-On