Use access tokens and refresh tokens

To make authorized requests to 10Duke APIs, your application must provide an OAuth access token in the request.

Your client application receives an access token after successful user 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.

Together with the access token, your client application may also receive a refresh token. When the access token expires, the 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.

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.

OIDC/OAuth tokens

Are you new to access tokens and refresh tokens? Check out the basics below.

Access token and refresh token

After your client application has completed an OIDC/OAuth flow, 10Duke Enterprise grants the following OAuth tokens to your client application as the result of API authorization:

  • Access token

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

    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.

  • Refresh token

    The refresh token enables your client application to obtain a new access token when the current access token expires, without having to ask the end user to log in again. The refresh token is a random character string.

    By default, refresh tokens are only granted to confidential clients that use a client secret.

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. You also define per connection if refresh tokens are granted.

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

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 HTTP/1.1
   Host: {BASE_URL}
   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