info@10duke.com

Use access tokens and refresh tokens

To make authorized requests to 10Duke APIs for an authenticated end user, 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.

OAuth/OIDC tokens

Are you new to access tokens, refresh tokens, and ID 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 on behalf of the end user. 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.

ID token

With OIDC, 10Duke Enterprise also grants a standard OIDC ID token to your client application. The ID token is a JSON Web Token (JWT) that contains the details of the authenticated end user.

The ID token contains user information according to the scope names that your client application sent to 10Duke Enterprise when starting the OIDC/OAuth 2.0 flow. See more information on supported scopes.

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 have no maximum validity time.

  • In addition, you can attach the token validity to the end user’s user session. This means the token also expires if the end user logs out (the session ends). With the default configuration, this means the maximum validity of refresh tokens 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 end user selects “Remember me” when logging in.

    Note: If you use any client applications in the detached mode with an authentication flow that grants refresh tokens, we highly recommended that a separate maximum validity time is configured for refresh tokens. Otherwise refresh tokens are 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.

The maximum validity time of ID tokens is also configurable in 10Duke Enterprise. The default validity is the same as the access token default validity, 1 hour.

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 on behalf of a user, 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

Example request:

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

On this page