# Authentication

> Authenticate Ours Privacy REST API requests with organization API keys or OAuth access tokens issued by Ours Privacy, with live organization permissions enforced on every request.

Source: https://docs.oursprivacy.com/docs/platform-api/authentication

The Ours Privacy REST API accepts **organization API keys** and **OAuth access tokens issued by Ours Privacy**. Both credentials use the `Authorization` header.

```bash
Authorization: Bearer <your_api_key>
```

***

## OAuth Access

OAuth is the preferred authentication method for AI assistants and other interactive clients that support MCP authorization, such as Claude. You sign in to Ours Privacy in the browser, choose the organization to connect, and approve access. There is no client ID or secret to configure: the client identifies itself with its published OAuth client metadata, and the flow uses PKCE.

Before anyone can connect with OAuth, an organization **admin** must turn on **OAuth connections** under **Settings → Account Settings**. It is off by default, and turning it off again stops every OAuth connection in the organization immediately.

A connection carries the member's full current permissions, including writes. For a narrower credential, use a read-only API key or connect as a member with a limited role.

Use the same bearer header with an OAuth access token:

```bash
Authorization: Bearer <your_oauth_access_token>
```

The configured scopes are:

| Scope            | Purpose                              |
| ---------------- | ------------------------------------ |
| `openid`         | Identify the signed-in user          |
| `profile`        | Read profile information             |
| `email`          | Read the user's email address        |
| `offline_access` | Request refresh tokens               |
| `user:org:read`  | Select and identify the organization |

REST API access requires `openid` and `user:org:read`. The other configured scopes support profile, email, and refresh behavior. None of these scopes grant REST permissions. The API checks the selected organization's **OAuth connections** setting, which is off by default, and the member's current Ours Privacy permissions for every request, including writes.

The REST API and MCP server use the shared OAuth resource `https://ai.oursprivacy.com/mcp`. The OpenAPI authorization URL includes `prompt=consent` and this `resource`. MCP clients that follow the Model Context Protocol authorization flow discover these values automatically and show the organization selector and consent screen when you connect. Refreshes happen silently and stay with the same organization.

MCP protected-resource metadata is published at `https://ai.oursprivacy.com/.well-known/oauth-protected-resource/mcp`. The root `https://ai.oursprivacy.com/.well-known/oauth-protected-resource` path remains a fallback.

Ours Privacy admits clients that publish an OAuth client metadata document (the `client_id` is an HTTPS URL the client controls), which is how Claude identifies itself. Dynamic client registration is not available. OAuth is verified with Claude (claude.ai and Claude Desktop custom connectors); ChatGPT, Codex, Claude Code, and Cursor connect with an API key.

There is no per-connection list in Ours Privacy. To end one connection, disconnect it in the client. To end access for a person, an administrator removes them from the organization or changes their permissions; to end it for everyone, turn off **OAuth connections**.

***

## Creating an API Key

People with the **Manage API Keys** permission (`organization:manage-api-keys`) can open **Settings → API Keys** and create API keys. The scope picker lists only the scopes the creator holds. Members with this permission see and revoke only the keys they created. Organization admins with this permission can manage all of the organization's keys.

### Step 1: Enable API Keys

An organization admin turns on **API token access** under **Settings → Account Settings**. It is off by default, and turning it off stops every key in the organization. If you don't see the API Keys section, ask your account administrator.

### Step 2: Create a Key

1. Go to **Settings → API Keys** in your Ours Privacy dashboard
2. Click **Create API Key**
3. Pick an expiration: `1`, `3`, `7`, `30`, `90`, or `365` days
4. Select the scopes your key needs (see [Scopes](#scopes) below)
5. Click **Create**

> **Important:** Copy your API key immediately after creation. For security, the full key is only shown once and cannot be retrieved later.

Every API key has a fixed expiration. There are no permanent keys. Rotate in [API Keys](https://app.oursprivacy.com/admin/api-keys) by creating a fresh key before the old one expires and updating any integration using it, then revoke the old key once nothing depends on it.

### Expiration warnings

Contact your account representative to turn on expiration warnings for your organization. Once on, warnings are scheduled for the UTC calendar dates 15, 7, and 1 days before a key expires. A daily check sends the most recent due warning for an active key, so warnings are based on calendar dates rather than exact hours. A key created on or after a warning date will not receive that warning.

Warnings go by email and in-app to the key's creator if they are still an organization member with the **Manage API Keys** permission, and to current organization admins with that permission. Other members do not receive warnings about the key. The notice names the key and its expiration time and links to **API Keys** for rotation.

You can turn off email or in-app warnings separately under **API key expiration** in your [notification preferences](https://docs.oursprivacy.com/docs/notification-preferences). **Pause all** also stops these warnings for you in the current organization.

![Account Settings with the API token access and OAuth connections switches, each with a short description of what turning it on allows.](https://docs.oursprivacy.com/img/platform-api/platform-api-img-2.jpg)

![Notification preferences with API key expiration Email and In-app enabled and Pause all notifications turned off.](https://docs.oursprivacy.com/img/platform-api/platform-api-img-1.jpg)

### Step 3: Store It Securely

Treat your API key like a password. Store it in a secrets manager, environment variable, or encrypted configuration. Never commit it to source control.

***

## Scopes

API keys are scoped to control which resources and actions they can access. You can grant either broad or granular access:

| Scope                  | Description                                                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all`                  | Full access to all API resources and actions                                                                                                                           |
| *Specific permissions* | Grant access to individual resources (e.g., destinations, sources, consent settings). Uses the same permission model as your organization's role-based access control. |

When a request requires a scope the key doesn't have, the API returns `403 Forbidden` before any operation is executed.

***

## Verifying a Credential

`GET /rest/v1/me` returns the organization behind the current credential and its expiration. It checks no resource permission, so an API key with any scope, or an OAuth access token carrying the standard `openid` and `user:org:read` scopes, can confirm it works before calling other endpoints. See [Credential Identity](https://docs.oursprivacy.com/docs/platform-api/credential-identity) for the response shape.

***

## How Authentication Works

For API keys, the API validates:

1. **Key format**: the `Authorization` header is present and correctly formatted
2. **Key validity**: the key has not been revoked or expired
3. **Organization status**: API token access is on for the organization
4. **Creator identity**: the user who created the key is still a member of the organization and is not locked or banned
5. **Scope check**: the key has the required scope, and the creator still holds the matching permission, for the requested resource and action

For OAuth access tokens, the API validates the token with the Ours Privacy authorization server, checks the shared MCP resource, confirms the user and organization membership, checks the organization's OAuth setting, and resolves the member's current permissions. These checks happen on every request.

If any check fails, the API returns an appropriate error:

| Status                    | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`        | Missing, invalid, revoked, or expired credential                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `403 Forbidden`           | Credential is valid but lacks the required permission. For OAuth, also returned when the organization's **OAuth connections** setting is off, the user is no longer a member of the selected organization, or the user account is locked or banned. Also returned by analytics routes (web analytics, attribution, funnels, journey flows, audience conversion reports) when the organization does not have analytics access enabled. Refreshing the token will not help; fix the setting, membership, or access instead |
| `429 Too Many Requests`   | OAuth token validation was rate limited. Honor the `Retry-After` header before retrying                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `503 Service Unavailable` | The authorization server did not respond in time. Retry after the `Retry-After` header                                                                                                                                                                                                                                                                                                                                                                                                                                   |

***

## Revoking a Key

People with the **Manage API Keys** permission can revoke keys from **Settings → API Keys**. Members can revoke only keys they created; organization admins can revoke any organization key, provided they have the permission. Revoked keys immediately stop working. Any in-flight or future requests using a revoked key will receive `401`.

***

## Best Practices

* **Use the narrowest scopes possible.** Don't use `all` if the key only needs to manage destinations.
* **Pick the shortest expiration that fits the use case.** Use `1` or `3` day keys for one-off scripts; reserve longer durations for stable CI/CD integrations.
* **One key per integration.** Create separate keys for different tools or pipelines so you can revoke one without affecting others.
* **Use OAuth for interactive clients.** OAuth refreshes silently for the selected organization; keep API keys for scripts, CI, and clients without OAuth support.
* **Monitor usage.** Audit which keys are active and revoke any that are no longer needed.

***

## Next Steps

* **[Quickstart](https://docs.oursprivacy.com/docs/platform-api/quickstart)**: Make your first API call
* **[Credential Identity](https://docs.oursprivacy.com/docs/platform-api/credential-identity)**: Confirm a credential's organization and expiration
* **[SDKs and MCP](https://docs.oursprivacy.com/docs/platform-api/sdks-and-mcp)**: Connect SDKs and AI assistants with API keys or OAuth
