Copy page

API

Scopes

Scopes limit what an access token can do in Tny. Choose them when you create a team or personal access token. Both token types use the same scopes. Start with the narrowest scope that covers your integration. The shared scopes guide explains how parent scopes and write access work.

Available scopes

Broad scopes

Link scopes

Domain scopes

Utility scopes

Handle a missing scope

The API does not reject a GraphQL request as a whole when the token lacks a scope. It returns null for each field the token cannot access and adds an error for it. The error's extensions list the required and granted scopes:

Code
{
  "data": {"team": null},
  "errors": [
    {
      "message": "The 'links' field requires all of the following scopes: ['tny:links:read'], but your token has only been granted the: ['tny:domains:read'] scopes.",
      "path": ["team", "links"],
      "extensions": {
        "requiredScopes": ["tny:links:read"],
        "grantedScopes": ["tny:domains:read"],
        "allScopesRequired": true
      }
    }
  ]
}

A null for a non-null field makes its parent null too, which is why team is null in this example. Remove the field from the query or create a token with the required scope. Retrying with the same token returns the same error.

The REST endpoints respond with 403 instead.

Example token configurations

Read links and domains

Use separate read scopes when an integration only needs links and domains.

Code
tny:links:read tny:domains:read

Manage links

Code
tny:links:write

Write access includes read access at the same level, so this token can also list and view links. For a server that shortens links, use a team access token so it keeps working when people join or leave the team.

Read everything

Use the broad read scope for reporting or monitoring across Tny.

Code
tny:read

Use URL utilities

Code
tny:utilities:read