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

# Authentication

> Authenticate with the Plugchoice API using OAuth 2.0 or personal access tokens.

All API requests must include a bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_TOKEN
```

## Personal access tokens

The simplest way to authenticate is with a personal access token. Generate one from your [dashboard settings](https://app.plugchoice.com/settings/personal-access-tokens).

<Steps>
  <Step title="Go to Settings">
    Navigate to **Settings > Personal Access Tokens** in the Plugchoice dashboard.
  </Step>

  <Step title="Create a token">
    Click **Create Token**, give it a descriptive name, and copy the token value. The token is only shown once.
  </Step>

  <Step title="Use the token">
    Include the token in the `Authorization` header of your API requests.
  </Step>
</Steps>

```bash theme={null}
curl https://app.plugchoice.com/api/v3/user \
  -H "Authorization: Bearer your_personal_access_token"
```

## OAuth 2.0

For third-party integrations, Plugchoice supports OAuth 2.0. The following grant types are available:

| Grant type         | Use case                                           |
| ------------------ | -------------------------------------------------- |
| Authorization code | Web apps that need user authorization              |
| Client credentials | Server-to-server communication                     |
| Refresh token      | Renewing expired access tokens                     |
| Device code        | Devices without a browser (e.g., charger displays) |

### Authorization code flow

<Steps>
  <Step title="Redirect to authorize">
    Redirect the user to the authorization endpoint:

    ```
    GET https://app.plugchoice.com/oauth/authorize
      ?client_id=YOUR_CLIENT_ID
      &redirect_uri=YOUR_REDIRECT_URI
      &response_type=code
      &scope=
    ```
  </Step>

  <Step title="Exchange code for token">
    After the user grants access, exchange the authorization code for tokens:

    ```bash theme={null}
    curl -X POST https://app.plugchoice.com/oauth/token \
      -d grant_type=authorization_code \
      -d client_id=YOUR_CLIENT_ID \
      -d client_secret=YOUR_CLIENT_SECRET \
      -d redirect_uri=YOUR_REDIRECT_URI \
      -d code=AUTHORIZATION_CODE
    ```
  </Step>

  <Step title="Use the access token">
    Use the returned `access_token` in the `Authorization` header:

    ```json theme={null}
    {
      "token_type": "Bearer",
      "expires_in": 31536000,
      "access_token": "eyJ0...",
      "refresh_token": "def5..."
    }
    ```
  </Step>
</Steps>

### Client credentials flow

For server-to-server integrations that don't require user authorization:

```bash theme={null}
curl -X POST https://app.plugchoice.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=
```

### Refreshing tokens

Use a refresh token to obtain a new access token:

```bash theme={null}
curl -X POST https://app.plugchoice.com/oauth/token \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=YOUR_REFRESH_TOKEN
```

### Revoking tokens

Revoke an authorized access token when it's no longer needed by deleting it by ID:

```bash theme={null}
curl -X DELETE https://app.plugchoice.com/oauth/tokens/TOKEN_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<Warning>
  Keep your client secret confidential. Never expose it in client-side code or public repositories.
</Warning>