# Authentication

The Understory API requires you to authenticate yourself in most endpoints.
To authenticate your requests you need to provide an access token which is based on your integration credentials.

## About the protocol

We use the standard [OAuth2.0 protocol](https://oauth.net/2/) with [Open ID Connect (OIDC)](https://openid.net/developers/how-connect-works/).
These are industry standards and most programming languages and frameworks support these out of the box.

## Which authentication method do I need?

Understory supports two authentication methods depending on your use case:

| **Method** | **Use Case** | **Grant Type** |
|  --- | --- | --- |
| [Internal Integration Keys](/docs/usage/authentication/integration-keys) | You are an Understory customer building tools to automate or extend your own Understory account. Your integration accesses only your own data. | `client_credentials` |
| [Third-Party Integration](/docs/usage/authentication/third-party-integrations) | You are building an application that will access other Understory customers' data with their permission. Examples include marketplaces, marketing tools, and accounting integrations. | `authorization_code` |


## Endpoint configuration

Below are the protocol endpoints which can be used to configure your client of choice.

| Description | Endpoint |
|  --- | --- |
| Issuer | `https://api.auth.understory.io` |
| OpenID Connect Discovery Endpoint | `https://api.auth.understory.io/.well-known/openid-configuration` |
| Token | `https://api.auth.understory.io/oauth2/token` |
| Authorize | `https://api.auth.understory.io/oauth2/auth` |


## Scopes

Scopes define what resources and actions your integration can access.
Request only the scopes your application needs following the [principle of least privilege](https://csrc.nist.gov/glossary/term/least_privilege).

| **Scope** | **Description** |
|  --- | --- |
| `booking.read` | Read access to bookings |
| `booking.write` | Create and modify bookings |
| `event.read` | Read access to events and availability |
| `experience.read` | Read access to experiences |
| `marketing.read` | Read access to marketing consents |
| `order.read` | Read access to orders |
| `webhook.read` | Read access to webhook subscriptions |
| `webhook.write` | Create, modify, and delete webhook subscriptions |
| `offline` | Enables refresh tokens for long-lived access (required for third-party integrations) |


Refer to the [API Reference](/apis) for detailed information about which endpoints require which scopes.