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.
We use the standard OAuth2.0 protocol with Open ID Connect (OIDC). These are industry standards and most programming languages and frameworks support these out of the box.
Understory supports two authentication methods depending on your use case:
| Method | Use Case | Grant Type |
|---|---|---|
| Internal 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 | 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 |
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 define what resources and actions your integration can access. Request only the scopes your application needs following the principle of 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 for detailed information about which endpoints require which scopes.