Registering OAuth Client in Timeline

To prepare for interaction with Timeline API, you need to register an OAuth client in your Timeline account beforehand. Registering such a client will allow exchanging information between your 3rd party system and Timeline:

  • The external system will receive some security credentials to interact with Timeline. Using those credentials your system will be able to retrieve information from Timeline API resources.
  • You will provide to Timeline the endpoint that should be prepared in your system for Timeline to interact with.

Access tokens are issued according to the OAuth client settings and are tied to it for management and security purposes. In other words, the OAuth client binds a 3rd party system to Timeline.

Important. You need to have an Account Owner or Admin role to be able to access the account section in Timeline, so the same access level is needed to create a new OAuth connection.

Follow the instructions below to set up the OAuth connection properly:

  1. Log into your Timeline account.
  2. Go to the account section by clicking your user avatar at the bottom of the left bar and then selecting Account. Then open the OAuth & OpenID Connect tab.
  3. Click on +Register client.
  4. In the opened dialog, fill in the client details fields with the information about your system:
    1. Name
      Enter a name to identify the new OAuth client.
    2. App URL
      Provide a link to your application's homepage. Users will see this link when asked to grant access to their information held in Timeline. This link is not involved in the connection process, its main objective is to give users a possibility to see what they are giving access to and make sure that it is a familiar and trusted system.
    3. Redirect URI
      Specify the Redirection Endpoint to be used to provide the OAuth Authorization Response. This should be the full URL of an endpoint in your application or system which you want to connect to Timeline. Since Timeline API is guarded by OAuth 2.0, this endpoint should be able to exchange an authorization code received from Timeline for an access token. This token will be used to authenticate your API calls later.
      Timeline will send an authorization code to this endpoint, and a user will be redirected to this URL after providing consent to give access to their Timeline account data.
      For more information on authentication in Timeline API, required access tokens, and supported authorization flows, see Access Token.

      External documentation. Learn more about Redirection Endpoint -
  5. Check the preview in the Client details section.
    After you fill in the information required in step 4, you can check the Client details preview with an example of what the users will see on the screen asking them for permission to share their Timeline-related information with your system. You can click on the default picture to upload your corporate logo or any other suitable image to assure users that they are interacting with a familiar and trusted system.
  6. In the Client type section, select which client type to use depending on which fits best to your type of application:
    1. Confidential
      Select this option if your application can securely hold credentials without exposing them to unauthorized parties, and you have a trusted backend server to store secrets.
      For example, if you have a web application with a user interface and a server-side component (API server, auth server, etc.) you can choose the confidential type as your server-side component will be able to securely store issued credentials.
      This type is the most secure one, and we recommend using it.
    2. Public
      Your application fits this category if it cannot hold credentials securely. In this case, a client secret will not be issued for you as your application is not able to securely store it, and, for example, is running entirely in the browser.
      Important. Public clients must use the Authorization Code grant with the PKCE addition.

      External documentation. Learn more about Client Types -
  7. In the Grant type section, select the authorization flow that your users will need to use to be able to authenticate their requests.
    Obtaining an access token in OAuth is accomplished by performing one of the "Grant types". Timeline supports Authorization Code and Client Credentials authorization grants, aligning with the latest OAuth 2.0 Security Best Practices. In addition, a Refresh Token option is available.
    External documentation. OAuth 2.0 Security Best Practices -
    Important. The Client Credentials authorization grant is not supported for API interaction at the moment, so this option is skipped in this instruction.

    Select one or both of the following options:
    1. Authorization Code
      This option is selected by default. This grant type is used to exchange an authorization code for an access token. We recommended to use it since it has the most secure flow.
      Also, Timeline supports the PKCE addition for this grant type, which is recommended to use if you select the Authorization Code grant type.
    2. Refresh Token (optional)
      It is a special type of token used to obtain additional access tokens. A refresh token has a longer lifespan, so it allows receiving new short-lived access tokens without having to collect credentials every time they expire.
      If you would like to refresh expired access tokens for your users without additional steps, select this grant type as well.
      External documentation. Learn how to refresh an expired access token -
  8. Select this option to enable OpenID Connect. It allows getting certain information about authenticated end-users. If enabled, a special "openid" scope value is sent with the authorization request. This causes Timeline's Authorization Server to generate and return an id_token alongside of the access_token. The id_token provides information about the authenticated Timeline user with the values from their profile. The disclosed information can be set by selecting the needed options in the appeared Claims list: email, name, given_name, family_name, phone_number, locale, zoneinfo.

    Important. After the OAuth client is registered, these selections cannot be changed.
    External documentation. Read more on OpenID Connect in the official core documentation - OpenID Connect Core:
    For details on OpenID Connect in Timeline, see OAuth & OpenID Connect.
  9. Select permission Scopes that will be available for this OAuth client. Scopes are tied to access tokens. This means that an issued token can grant access only to those API endpoints, which require the scopes associated with this token. For example, to get a user’s project list requires an access token with the scope that allows read-only access to Timeline projects - project:read. If this scope is not associated with the access token, the call to the endpoint fails.
    Select the absolute set of scopes that an end user or an application will use:
    1. Read projects (project:read)
      Allows making GET requests to the Projects resource.
    2. Write projects (project:write)
      Allows making all kinds of requests to the Projects resource.
    3. Read repositories (repository:read)
      Allows making GET requests to the Repositories resource.
    4. Write repositories (repository:write)
      Allows making all kinds of requests to the Repositories resource.

      It is recommended to select only the scopes that are really needed for the expected requests, otherwise, users interacting with this client might decline the connection because they do not want to grant more permissions than are actually needed. For example, if you expect only the requests to read the user’s project list through this client, the Read projects scope is sufficient.
  10. When the configuration is finished, click Register. The OAuth dialog will re-open with two additional fields pre-filled: Client ID and Client Secret. These are your OAuth credentials needed for any of the supported OAuth grant types.
    Note. A client secret won’t be issued if your client type is Public.

Now when you have a properly configured OAuth client that will be used when performing one of the supported OAuth authorization flows to get an access token. At the moment, for the API the Authorization code grant is required. For further instructions, see Access Token.

22.02.2024 17:28:05

Usage of Cookies. In order to optimize the website functionality and improve your online experience ABBYY uses cookies. You agree to the usage of cookies when you continue using this site. Further details can be found in our Privacy Notice.