Use access tokens and refresh tokens

10Duke Enterprise grants an access token and a refresh token to your client application as the result of API authorization after the application has completed an OIDC/OAuth flow.

A client application that uses a client secret is called a confidential client, and other clients are public. All flows return an access token to the client, but by default, a refresh token is only returned to confidential clients. It’s possible to return a refresh token to any client if needed. In each client application connection in 10Duke SysAdmin, you define whether refresh tokens are granted to that client application.

Access tokens

The OAuth access token is the key that your client application must provide to make authorized API requests. It must be included in all API requests to 10Duke APIs.

Your client application receives an access token after successful user or device client authentication and API authorization with OIDC/OAuth 2.0. The access token is used in the same way regardless of the flow you used to get the token.

The access token is a random character string, and it’s always specific to both the client application that it was granted to and the authenticated user or device client.

Refresh tokens

Together with the access token, your client application may also receive an OAuth refresh token. The refresh token is a random character string.

When the current access token expires, your client application can use the refresh token to seamlessly obtain a new access token, without any interaction needed from the end user. The application also receives a new refresh token for the next refresh.

Your client application can continue to refresh the access token until the OAuth session expires. After that, the client application must perform the authentication again.

Configure token validity

The validity of access tokens and refresh tokens is controlled as follows:

  • The maximum validity time of access tokens and refresh tokens is configurable in 10Duke Enterprise.

    By default, access tokens are valid for a maximum of 1 hour, and refresh tokens are valid for a maximum of 30 days. This means the OAuth session expires after 30 days, and until then the client application can continue to refresh the access token.

  • In addition, you can attach the token validity to the user’s browser session when using an OIDC flow that uses a browser for user authentication. This means the tokens also expire if the user logs out (the session ends).

    With the default configuration, the maximum validity of the OAuth session is the same as the configured maximum validity of a user session—30 days by default.

    If the token validity is detached from the user session, the user session validity doesn’t restrict the token validity. You can also choose to only apply the detached mode when the user selects “Remember me” when logging in.

    Note: If you have any client applications that use an OAuth flow that grants refresh tokens, and you’re either using the detached mode or the token validity cannot be tied to the user session, we highly recommend that the configuration defines a maximum validity time for refresh tokens. Otherwise the OAuth session is valid indefinitely.

You define separately for each client connection in 10Duke SysAdmin whether the validity of these tokens is attached to the user session.

For 10Duke Enterprise configuration changes, contact the 10Duke Integration Support team.

Access 10Duke APIs using the access token

To make an authorized request to a 10Duke API, the request must include a Bearer token authorization header that specifies an OAuth access token.

Format:

Authorization: Bearer <token value>

Example:

Authorization: Bearer jev4s419f2ov2a13c8pjmhnekd

Note that accessing the 10Duke APIs also requires sufficient permissions, which vary for different API operations. When the client application is acting on behalf of a user, the client application uses the permissions that have been granted to the user. The client application can also have permissions of its own, especially in cases where there’s no user involved.

Refresh the access token

As described above, while the OAuth session is valid, you can continue to try and obtain new access tokens with the latest refresh token you have received. You find the amount of time (in seconds) until the OAuth session expiry in the refresh_token_expires_in field in the response that you received when obtaining the access token.

A refresh is not possible if the token validity is attached to the user session and the user has logged out, or their user session has been invalidated by some other means (for example, it has been deleted in SysAdmin).

An example request (line breaks added for display purposes):

POST /user/oauth20/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=refresh_token
   &refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
   &scope=openid%20profile
   &client_id=todo_api_key
   &client_secret=todo_client_secret

The response contains a new access token with a new expiry time, and a new refresh token. The seconds until the OAuth session expiry in refresh_token_expires_in stays the same.

Request information on a token

Typically the information received with the access token and refresh token is sufficient for the client application, but if needed it can request for additional information on either token from 10Duke Enterprise. See more information on OAuth token introspection in RFC 7662.

Authorize the request by including a Bearer token authorization header that specifies either a valid access token or refresh token for the same OAuth session as the token that the client application is requesting information on.

An example request (line breaks added for display purposes):

POST /user/oauth20/introspect
   Content-Type: application/x-www-form-urlencoded
   Authorization: Bearer jev4s419f2ov2a13c8pjmhnekd

   token=jev4s419f2ov2a13c8pjmhnekd
   &token_type_hint=access_token

In token, include the token that you’re requesting information on, and in token_type_hint, use either access_token or refresh_token to specify the type of that token.

An example response:

{
  "active":true,
  "scope":"openid profile email",
  "client_id":"test-client",
  "exp":1701166465,
  "refresh_token_expires_in":86400
}

In addition to the fields specified in RFC 7662, when you request information on an access token the response specifies the seconds until the OAuth session expiry in refresh_token_expires_in.

On this page