Aller au contenu

API keys

An API key lets a script or a tool call the API as you, without your password. It is the simplest way to authenticate.

Create a key

  1. In the web app, click your name at the bottom of the menu to open My account.
  2. Open the API keys tab and click New API key.

  3. Fill in the form:

    Name
    What or who uses the key, to recognise it later: "Power BI export", "ERP sync".
    Access
    Read only to read projects, tasks and documents. Read and write to also create, change and delete them. Choose read only when it is enough.
    Expires after
    30 days, 90 days or 1 year. An expired key stops working; create a new one to replace it.

  4. Click Create key, then Copy.

The key is shown once

Touch2build keeps only a fingerprint of the key, never the key itself, so nobody can show it to you again. Store it at once in a password manager or in the secret store of your tool. If you lose it, revoke it and create another one.

You can hold 20 active keys at most.

Use the key

Send the key in the Authorization header of every request, as a bearer token:

GET /v1/projects HTTP/1.1
Host: api.touch2build.com
Authorization: Bearer t2b_live_3kq9XbW2mT7a_...

curl https://api.touch2build.com/v1/projects \
  -H "Authorization: Bearer $T2B_API_KEY"

import os
import requests

api = requests.Session()
api.headers["Authorization"] = f"Bearer {os.environ['T2B_API_KEY']}"

projects = api.get("https://api.touch2build.com/v1/projects", params={"limit": 100}).json()
for project in projects["data"]:
    print(project["id"], project["name"])

const response = await fetch("https://api.touch2build.com/v1/projects", {
  headers: { Authorization: `Bearer ${process.env.T2B_API_KEY}` },
});
const projects = await response.json();

$headers = @{ Authorization = "Bearer $env:T2B_API_KEY" }
Invoke-RestMethod https://api.touch2build.com/v1/projects -Headers $headers

What a key can do

  • As you. A key reaches the projects you can open in the app, with your permissions in each. If you leave a project or lose a permission, the key loses it too.
  • Within its access. A read-only key that tries to write gets 403 with the code insufficient_scope.
  • Only the API. A key cannot sign in to the web or mobile app, nor create other keys.

Keep keys safe

  • Never put a key in source code, in a URL, or in a page that runs in a browser. Read it from an environment variable or a secret store.
  • Use one key per tool, so that you can revoke one without stopping the others.
  • Prefer read-only keys and short validity periods.
  • Keys start with t2b_live_, so a secret scanner can be set to spot them in your repositories and logs. If a key leaks, revoke it.

Revoke a key

In My account › API keys, click Revoke on the key's row. The key stops working within seconds, and requests made with it get 401.

The table shows when each key was last used: a key unused for months is a good candidate for revocation. Show revoked and expired keys lists the others.

Replace a key before it expires

The Expires column warns you when a key expires in less than two weeks. To replace it without interruption:

  1. create a new key with the same access;
  2. put it in your tool and check that it works;
  3. revoke the old key.

OAuth for applications

An API key suits your own scripts and integrations. An application that other Touch2build users sign in to should use OAuth 2.0 (authorization code with PKCE) instead, so that each user grants it access and nobody shares a key. Write to support@touch2build.com to register an application.