# Getting credentials

Both APIs take a key you create yourself. Here is where each one lives.

The two products have separate credentials with separate lifecycles, and holding one grants nothing on the other. Pick the product you are calling.

[GeoDynamics API An API token, created in IntelliTracer `itr_pat_...`](#geodynamics-api) [Proof API A service key, created in Proof `sk_...`](#proof-api)

## GeoDynamics API: create an API token

You need the privilege to manage API tokens. If the menu item is missing, ask whoever administers your IntelliTracer environment.

1.  In IntelliTracer, go to **Config**, then **Company**, then **API tokens**. It sits next to Webhooks.
2.  Press **Add**.
3.  Give the token a name. Name it after the integration that will use it, so the list stays readable and you know what breaks if you delete one.
4.  Select the privileges the integration needs. These become the token's scopes, and the same privilege checks run on every call, so a token granted only location reads cannot write clockings.
5.  Press **Save**.

The token appears in the list, starting with `itr_pat_`. It belongs to the company rather than to a person, so it keeps working when someone leaves. The full token stays readable on that screen, so anyone who can open the list can copy it again.

```plain title="header.txt"
Authorization: Bearer itr_pat_1a2b3c...
```

### Rotating and revoking

Deleting a token stops it working immediately. To rotate without downtime: add the replacement, move your integration onto it, then delete the old one.

## Proof API: create a service key

Service keys are managed per environment, so create the key in the environment whose data the integration should reach.

1.  In Proof, go to **Settings**, then **Service keys**.
2.  Give the key a name.
3.  Tick the scopes it needs. There are four: read and manage on workplace groups, read on workplaces, and read on users.
4.  Press **Add service key**.

The key appears in the list with its token, starting with `sk_`. It stays readable there, so you can copy it again later. The list also shows when each key was last used, which is the quickest way to tell a live integration from an abandoned one.

```plain title="header.txt"
Authorization: Bearer sk_1a2b3c...
```

A key belongs to one environment, which is why no Proof call takes an environment parameter. A key that authenticates but lacks the scope for the call gets `403`, not `401`. The scopes in full:

- **`public:scope:workplacegroup:read`**: List workplace groups and read one by id.
- **`public:scope:workplacegroup:manage`**: Create, update and delete groups, and set their workplaces and users.
- **`public:scope:workplace:read`**: List the workplaces in the environment.
- **`public:scope:user:read`**: List the active users in the environment.

## Keeping the key safe

-   One credential per integration, named after it. Retiring the integration is then a single delete with no collateral.
-   Grant the narrowest set of scopes that does the job.
-   Store it in a secrets manager (Vault, AWS Secrets Manager, CF Secrets, Doppler), never in source control.
-   Send it only in the `Authorization` request header, over HTTPS with TLS 1.2 or higher. Query-string credentials are not accepted.