> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate to org-wide and user-scoped APIs with one client app.

Siro is consolidating API auth onto **client apps**. One credential can call both the org-wide API (`functions.siro.ai`) and the user-scoped API (`api.siro.ai`).

Organization API tokens and Siro OAuth apps still work. New integrations should use client apps. Org API tokens follow the timeline below. Siro OAuth apps stay valid until a separate decommission date is announced.

## What replaces what

| Today                                                       | Use instead             | Notes                               |
| ----------------------------------------------------------- | ----------------------- | ----------------------------------- |
| Org API token (`Authorization: Bearer`, org-wide API only)  | Client app access token | Same `Authorization: Bearer` header |
| Siro OAuth app + `x-siro-auth-token` (user-scoped API only) | Client app access token | Same `x-siro-auth-token` header     |

Client apps are org-scoped machine credentials. They are not tied to a logged-in user.

## Timeline

Dates are measured from the client app release.

| When                                  | What happens                                                                         |
| ------------------------------------- | ------------------------------------------------------------------------------------ |
| Client app release                    | Client apps are available. Existing org API tokens and Siro OAuth apps keep working. |
| 30 days after release                 | Creating new org API tokens is turned off. Tokens that already exist keep working.   |
| 9 months after creation is turned off | Org API tokens are decommissioned. They no longer authenticate.                      |

## Walkthrough

### 1. Create a client app in the Siro web app

As an org admin, create a client app in the Siro web app under the `API access` tab. Copy the `client_id` and `client_secret` when they are shown — the secret is returned **once**. Rotate or revoke from the same UI.

### 2. Exchange credentials at auth.siro.ai

```bash theme={null}
curl --request POST \
  --url "https://auth.siro.ai/oauth2/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data "client_id=$CLIENT_ID" \
  --data "client_secret=$CLIENT_SECRET"
```

Response: `access_token`, `token_type: bearer`, `expires_in` (typically 3600 seconds). There is no refresh token — mint again before expiry. Full reference: [Get an access token](/api-references/get-a-client-app-access-token).

### 3. Call either API

**Org-wide**

```bash theme={null}
curl --request GET \
  --url "https://functions.siro.ai/api-externalApi/v1/core/recordings?pageSize=100" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

**User-scoped**

```bash theme={null}
curl --request GET \
  --url "https://api.siro.ai/v1/core/recordings/$RECORDING_ID?showSummary=true" \
  --header "x-siro-auth-token: $ACCESS_TOKEN"
```