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

# Authentication

> Authenticate with Phonovation using a personal access token or an OAuth access token.

Every authenticated Phonovation API request uses a bearer token. For most integrations, use a personal access token (PAT) generated in the Phonovation application. Use OAuth only when your integration needs an access-token and refresh-token lifecycle.

```mermaid title="Choose an authentication method" actions={false} theme={"dark"}
%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Outfit", "fontSize": "11px", "primaryColor": "#fff1ef", "primaryTextColor": "#0f1926", "primaryBorderColor": "#d23a25", "lineColor": "#4b69a0", "secondaryColor": "#eaf0fa", "tertiaryColor": "#edf8f0"}, "flowchart": {"nodeSpacing": 12, "rankSpacing": 16, "diagramPadding": 2}}}%%
flowchart LR
  Choice{"Need OAuth?"}
  Choice -->|"No"| PAT["Use a PAT"]
  Choice -->|"Yes"| OAuth["Use an OAuth token"]
  PAT --> Header["Bearer token"]
  OAuth --> Header
  Header --> API["Call the API"]

  classDef app fill:#eaf0fa,stroke:#4b69a0,color:#0f1926,stroke-width:2px
  classDef auth fill:#fff1ef,stroke:#d23a25,color:#0f1926,stroke-width:2px
  classDef ready fill:#edf8f0,stroke:#247a4b,color:#0f1926,stroke-width:2px
  class Choice app
  class PAT,OAuth auth
  class Header,API ready
```

## Personal access tokens

Generate and manage PATs in [Phonovation developer settings](https://app.phonovation.com/developer?tab=pat-tokens). PAT values begin with `phv_pat_`.

<Steps>
  <Step title="Generate the PAT">
    Create the PAT once in the Phonovation application. Copy it when it is shown.
  </Step>

  <Step title="Store it securely">
    Put the PAT in a secrets manager or another protected runtime secret. Never commit it to source control or include it in logs.
  </Step>

  <Step title="Use it as a bearer token">
    Preserve the token's casing and include it in the `Authorization` header:

    ```bash title="Authenticated request" lines focus={2} wrap theme={"dark"}
    curl https://api.phonovation.com/v1/campaign/CAMPAIGN_ID \
      -H "Authorization: Bearer YOUR_TOKEN"
    ```
  </Step>

  <Step title="Rotate when needed">
    Replace the PAT when it expires, is revoked, or you intentionally rotate it. You do not generate a new PAT for each SMS.
  </Step>
</Steps>

## Optional OAuth tokens

The OAuth endpoint is available for integrations that specifically need a token lifecycle:

```text title="OAuth token endpoint" highlight={1} theme={"dark"}
POST https://auth.phonovation.com/token
```

Send the request as `application/x-www-form-urlencoded` with the OAuth client ID `messaging-api`.

<Tabs>
  <Tab title="Password grant">
    Exchange a Phonovation username and password for an access token and refresh token. This compatibility flow must be enabled for the `messaging-api` client.

    ```bash title="Obtain OAuth tokens" lines focus={3-6} wrap theme={"dark"}
    curl -X POST https://auth.phonovation.com/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data-urlencode "client_id=messaging-api" \
      --data-urlencode "grant_type=password" \
      --data-urlencode "username=YOUR_USERNAME" \
      --data-urlencode "password=YOUR_PASSWORD"
    ```
  </Tab>

  <Tab title="Refresh token grant">
    Reuse the access token until it is close to expiry. Then exchange its refresh token for a new access token.

    ```bash title="Refresh an OAuth token" lines focus={4-5} wrap theme={"dark"}
    curl -X POST https://auth.phonovation.com/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data-urlencode "client_id=messaging-api" \
      --data-urlencode "grant_type=refresh_token" \
      --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"
    ```
  </Tab>
</Tabs>

A successful response includes `access_token`, `expires_in`, and `token_type`. It can also include `refresh_token` and `refresh_expires_in`. Use the lifetimes returned by the API instead of assuming fixed values.

## Use the token

PATs and OAuth access tokens use the same header:

```http title="Authorization header" highlight={1} theme={"dark"}
Authorization: Bearer YOUR_TOKEN
```

The health endpoint is public. Campaign creation and campaign-summary requests require authentication.

## Authentication errors

| Response            | Meaning                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `400` from `/token` | Credentials, grant data, or the refresh token is missing or invalid                                                   |
| `401`               | The bearer token is missing, malformed, invalid, expired, or revoked                                                  |
| `403`               | The token is valid, but the identity is not linked to an active recognized Phonovation client or client administrator |

<Card title="Authentication API Reference" icon="key" href="/phonovation-api/api-reference/authentication/obtain-access-token">
  Review the complete OAuth request and response schemas.
</Card>