Skip to main content

Authenticating with the Web API v3

How to request an access token and which scopes to use

Written by TinQwise Service

Every request to the Web API v3 needs an access token. This article explains how to get one and which scopes to ask for.

Part of Web API v3 for user management.

How authentication works

To connect with the API in a secure way we support OAuth2 with the Client Credentials Grant flow.

A client_id, client_secret and scope are needed to request an access token that can be used for authentication.

Getting your credentials

To request a client_id and client_secret, contact Quinn or email service@tinqwise.com. Please specify which scopes you require.

Requesting a token

Using your client_id and client_secret, request an authorization token using the Token URL.

Click the Authorize button in your interactive documentation to see your token URL.

[📸 SCREENSHOT: The interactive documentation page with the Authorize button highlighted, showing where the Token URL appears]

This token is necessary when you send a request to our API. Send it in the Authorization header of every request: Authorization: Bearer <access_token>.

🚧 Be careful

A token only has the scopes you list in the scope parameter when you request it, even if your API client is allowed to use more. Request all scopes you need at once, separated by spaces, for example scope=v3:users:read v3:users:write v3:groups:read v3:groupmemberships:read v3:groupmemberships:write. The token response lists the scopes the token received in its scope field.

👀 Good to know

A token is valid for 10 hours; the expires_in field in the token response gives the lifetime in seconds. Request a token once and reuse it for all calls until it expires. Requesting a new token for every call doubles the number of requests your integration makes.

Read and write scopes

There are two scopes for each endpoint, for example v3:users:read and v3:users:write.

  • The read scope is required for GET requests.

  • The write scope is required for PUT, POST, PATCH and DELETE requests.

Available scopes

  • v3:users:read

  • v3:users:write

  • v3:groups:read

  • v3:groups:write

  • v3:groupmemberships:read

  • v3:groupmemberships:write

  • v3:permissions:read

  • v3:permissions:write

  • v3:activation_token:read

  • v3:activation_token:write

  • v3:budgets:read

  • v3:budgets:write

  • v3:todos:read

  • v3:todos:write

Troubleshooting

  • 401 Unauthorized (not_authenticated): the token is missing, expired or not sent correctly. Check that every request has the header Authorization: Bearer <access_token>, and request a new token if it has expired.

  • 403 Forbidden: the token does not have the scope for this endpoint and method. Check the scope field of your token response, and request a new token with the missing scope. If your API client is not allowed that scope, email service@tinqwise.com.

✏️ Tip

If a request fails in your own code, try the same request in the interactive documentation. If it works there, compare the scopes you request and the headers you send.

For a working request example, see the Python example in Web API v3 for user management.

Did this answer your question?