10Duke Enterprise release 3 documentation is no longer being updated

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 OAuth session expiry time in the refreshable_until 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 OAuth session expiry time in refreshable_until stays the same.

On this page