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

# Authentication

[OAuth 2.0](https://oauth.net/2/) standardized access tokens allow authenticated requests to be made to the Pipevest API.
This document will guide you on how to **create**, and **delete** authentication tokens.

## Creating an Auth Token

To create an Auth Token:

<Tip>
  Make a `POST` request to
  [/oauth/token](/api-reference/endpoint/authentication/create)
</Tip>

```bash theme={null}
  curl --request POST \
    --url https://api.pipevest.com/v1/oauth/token\
    --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
    --header 'Content-Length: 18' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "Content-Digest" "Content-Length" "Content-Type" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Idempotency-Key: <idempotency-key>' \
    ...
    --data 'clientId=<client-id>'
    --data 'clientSecret=<client-secret>'
```

<Note>
  The resulting access token has a
  [TTL](https://en.wikipedia.org/wiki/Time_to_live) of `60 mins`.
</Note>

## Revoke Auth Token

To revoke an auth token:

<Tip>
  Make a `POST` request to
  [/oauth/revoke](/api-reference/endpoint/authentication/revoke)
</Tip>

```bash theme={null}
  curl --request POST \
    --url https://api.pipevest.com/v1/oauth/revoke\
    --header 'Authorization: Bearer <access-token>' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Authorization" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: <client-id>' \
    --header 'X-Idempotency-Key: <idempotency-key>' \
```

## Entity Reference

| Property       | Definition                                           |
| -------------- | ---------------------------------------------------- |
| `message`      | Authentication response message                      |
| `tokenId`      | Unique access token identifier                       |
| `token`        | Client shortlived access token. TTL of `60 mins`     |
| `expiresIn`    | A token's current TTL                                |
| `maxTTL`       | A token's max time to TTL                            |
| `tokenType`    | A token's authorization type                         |
| `scope`        | The authorization scopes associated with token       |
| `trustedIps`   | The list of ip addresses whitelisted for this client |
| `organization` | An object containing `id`, `name` and `clientId`     |
| `createdAt`    | Created at unix timestamp                            |
| `updatedAt`    | Updated at unix timestamp                            |

<Note> Access token `tokenType` will always be `Bearer`</Note>

## Webhook Subscriptions

| Subscription   | Definition                                | Domain          |
| -------------- | ----------------------------------------- | --------------- |
| `AUTH`         | Only events that deal with authentication | Authentications |
| `AUTH.CREATED` | Triggered when an auth token is created   | Authentications |
| `AUTH.DELETED` | Triggered when an auth token is deleted   | Authentications |

<Card title="Authentication Concepts" icon="user-shield" href="/concepts/authentication" horizontal>
  Check out the auth mechanisms used to keep the API secure
</Card>