# Authentication

A scoped API token, sent as a bearer token.

The GeoDynamics API takes a company-level Personal Access Token. Send it in the `Authorization` header with the `Bearer` scheme on every request. OAuth signs users into the portal and other applications; it is not an API credential.

## API tokens

A token that belongs to the company rather than to a person, so it keeps working when someone leaves. Create one in IntelliTracer under **Config**, **Company**, **API tokens**, next to Webhooks. You need the privilege to manage API tokens to see that page. Full walkthrough: [Getting credentials](/docs/workspaces).

```plain title="token.txt"
token:   itr_pat_ followed by 64 hex characters

header:  Authorization: Bearer itr_pat_1a2b3c...
```

You choose the token's scopes when you create it. A scope is an API privilege, and the list you can pick from is your company's privileges narrowed to the ones that actually gate an endpoint. The same privilege checks then run on every call, so a token granted only location reads cannot write clockings. The full token stays readable on the token screen, so treat that screen like a secrets surface.

A complete request:

```curl title="api-token.sh"
curl https://api.geodynamics.dev/intellitracer/v1/resourcegroups \
  -H "Authorization: Bearer $GD_API_TOKEN"
```

```node title="api-token.ts"
const res = await fetch(
  "https://api.geodynamics.dev/intellitracer/v1/resourcegroups",
  { headers: { Authorization: `Bearer ${process.env.GD_API_TOKEN}` } },
);
```

```python title="api-token.py"
import os, requests

res = requests.get(
    "https://api.geodynamics.dev/intellitracer/v1/resourcegroups",
    headers={"Authorization": f"Bearer {os.environ['GD_API_TOKEN']}"},
    timeout=10,
)
```

### In practice

-   One token per integration, named after it. When you retire the integration you delete its token and nothing else breaks.
-   Grant the narrowest set of scopes that does the job. You can change a token's scopes later without reissuing it.
-   Store the token in a secrets manager (Vault, AWS Secrets Manager, CF Secrets, Doppler). Never in source control.
-   Deleting a token in IntelliTracer stops it working immediately. That is the rotation and revocation path: create the replacement, move your integration over, delete the old one.
-   All requests must use HTTPS with TLS 1.2 or higher.