OAuth2 authorization for the timr REST API

Overview

Integrations that call the timr REST API authenticate with OAuth2. Instead of using a timr username and password, an application receives an access token from the timr authorization server and sends that token with every API request. timr supports two grant type configurations — Client Credentials for machine-to-machine integrations that run without a user login, and Authorization Code with refresh token for integrations that act on behalf of an individual timr user who signs in. This article explains the OAuth basics, how to create API credentials in timr, and how to obtain and use access tokens for both flows. It is intended for administrators and developers building integrations against the timr API.
 

1. Prerequisites

• You need to be a timr administrator to create API credentials.
• Decide which grant type your integration requires before you start (see section 3).
• For the Authorization Code flow, you need at least one absolute redirect URL that your application controls.
   

2. OAuth basics

OAuth is designed to give controlled access to protected resources without sharing user passwords with third-party applications. The following formal roles apply:

• Resource Owner — the entity granting access to protected resources. Depending on the flow, this is the timr client or an individual timr user.
• Resource Server — the entity hosting the protected resources. In timr, this is the timr API.
• OAuth Client — the application that requests access to protected resources.
• Authorization Server — the entity that authenticates the resource owner, obtains authorization, and issues tokens to the OAuth client.
   

3. Choosing the right grant type

timr supports two grant type configurations. Choose the one that matches your integration:

• Client Credentials — Use this for machine-to-machine integrations where no individual timr user signs in. The access token is issued for the timr client and grants API access in the client context, so it can access data across users according to the API permissions associated with client_credentials.
• Authorization Code with refresh token — Use this when the integration acts on behalf of an individual timr user who explicitly signs in. The access token is issued in the context of that authenticated user and is limited by that user's permissions. It does not automatically grant tenant-wide client access.
   

4. OAuth endpoints

The OpenID discovery endpoint provides the relevant OAuth endpoints for the timr authorization server:

https://system.timr.com/id/.well-known/openid-configuration

Use the discovery document to look up the current authorization endpoint and token endpoint. For production timr, the commonly used endpoints are:

• Authorization endpoint: https://system.timr.com/id/oauth2/authorize
• Token endpoint: https://system.timr.com/id/oauth2/token
• API base URL: https://api.timr.com/v1
   

5. Creating API credentials in timr

To create a new OAuth client, proceed as follows:

1. Open timr in the web application and go to Administration → Settings → Integrations.
2. Under API Credentials, click + Add.
3. Enter a name and select the grant type for the client.
4. Save the client.

After creating the OAuth client, timr shows the OAuth Client ID and OAuth Client Secret.

Note: Store the client secret securely. It is required when requesting tokens and is shown only in the administration interface.

6. Client Credentials Flow

Use the Client Credentials Flow for machine-to-machine integrations where no individual timr user signs in. Client Credentials clients use the scopes openid timrclient.

To obtain a token, send a POST request to the token endpoint with the Content-Type header set to application/x-www-form-urlencoded:

POST /id/oauth2/token HTTP/1.1
Host: system.timr.com
Content-Type: application/x-www-form-urlencoded

client_id=<OAuth Client ID>&client_secret=<OAuth Client Secret>&grant_type=client_credentials&scope=openid timrclient

A successful response has status 200 OK and contains an access token:

{
    "access_token": "<access_token>",
    "scope": "openid timrclient",
    "token_type": "Bearer",
    "expires_in": 3599
}

Note: The Client Credentials Flow does not return a refresh token. When the access token expires, request a new access token with the same request.
 

7. Authorization Code Flow with refresh token

Use the Authorization Code Flow when the integration acts on behalf of an individual timr user. The user signs in at the timr authorization server, and the access token is issued in the context of that authenticated user. Authorization Code clients use the scopes openid offline_access. The offline_access scope allows the authorization server to issue a refresh token together with the access token.
 

7.1 Configuring redirect URLs

Authorization Code clients require at least one allowed redirect URL. Configure the redirect URLs when creating or editing the OAuth client in the timr web administration interface. Redirect URLs must be absolute URLs and must not contain a fragment. Configure one URL per line.

Valid examples:

https://example.com/oauth/timr/callback
https://app.example.com/integrations/timr/callback

Invalid examples:

/oauth/timr/callback
https://example.com/oauth/timr/callback#fragment

Note: The redirect_uri used in the authorization request and token request must exactly match one of the configured redirect URLs.
 

7.2 Requesting authorization and tokens

Step 1: Redirect the user to the authorization endpoint

Open the authorization endpoint in the user's browser:

GET /id/oauth2/authorize?response_type=code&client_id=<OAuth_Client_ID>&redirect_uri=<Redirect_URL>&scope=openid%20offline_access&state=<State> HTTP/1.1
Host: system.timr.com

Parameters:

• response_type — Must be code.
• client_id — The OAuth Client ID from the timr web administration interface.
• redirect_uri — One of the configured redirect URLs.
• scope — Use openid offline_access.
• state — A random value generated by your application. Store it before redirecting the user and verify it when the user returns.

After the user signs in, timr redirects the browser back to the configured redirect URL:

https://example.com/oauth/timr/callback?code=<Authorization Code>&state=<State>

Verify that the returned state value matches the value your application generated before redirecting the user.

Step 2: Exchange the authorization code for tokens

Send a POST request to the token endpoint with the Content-Type header set to application/x-www-form-urlencoded:

POST /id/oauth2/token HTTP/1.1
Host: system.timr.com
Content-Type: application/x-www-form-urlencoded

client_id=<OAuth Client ID>&client_secret=<OAuth Client Secret>&grant_type=authorization_code&code=<Authorization Code>&redirect_uri=<Redirect URL>

A successful response has status 200 OK and contains an access token and a refresh token:

{
    "access_token": "<access token>",
    "refresh_token": "<refresh token>",
    "scope": "openid offline_access",
    "token_type": "Bearer",
    "expires_in": 3599
}

Step 3: Refresh the access token

When the access token expires, send a refresh token request:

POST /id/oauth2/token HTTP/1.1
Host: system.timr.com
Content-Type: application/x-www-form-urlencoded

client_id=<OAuth_Client_ID>&client_secret=<OAuth_Client_Secret>&grant_type=refresh_token&refresh_token=<Refresh Token>

A successful response returns a new access token:

{
    "access_token": "<access token>",
    "refresh_token": "<refresh token>",
    "scope": "openid offline_access",
    "token_type": "Bearer",
    "expires_in": 3599
}

Note: If the response contains a new refresh token, replace the previously stored refresh token with the new one.
 

8. Using the access token

Use the access token when calling the timr API by sending it as a Bearer token in the Authorization header:

GET /v1/<resource> HTTP/1.1
Host: api.timr.com
Authorization: Bearer <access_token>

9. Frequently asked questions

Which grant type should I use? Use client_credentials when your integration is a backend service and should access timr in the client context without a user login. Use authorization_code with a refresh token when a user explicitly signs in and the integration should access timr with that user's permissions.

Why did I not receive a refresh token? The Client Credentials Flow does not return a refresh token. Request a new access token with the same token request when the current one expires. Refresh tokens are issued only in the Authorization Code Flow, and only when the offline_access scope is included.

What permissions does an access token grant? A token from the Client Credentials Flow grants API access in the client context according to the API permissions associated with client_credentials. A token from the Authorization Code Flow is limited to the permissions of the authenticated timr user.

Why is my authorization request rejected? Confirm that the redirect_uri in the request exactly matches one of the redirect URLs configured for the OAuth client, that the URL is absolute, and that it does not contain a fragment.
 

Further reading

• What Is OAuth? A Breakdown for Beginners | Nordic APIs
• What is OAuth 2.0 and what does it do for you? | Auth0
• RFC 6749: The OAuth 2.0 Authorization Framework