Third-Party Integrations

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

This guide explains how to build third-party applications that integrate with the Understory API on behalf of Understory customers. Third-party integrations use the OAuth 2.0 Authorization Code Grant flow, allowing your application to request access to a customer's Understory data with their explicit consent.

This is useful if you provide services that can use the data from Understory. Common examples are:

• Marketplaces
• Marketing tools
• Accounting systems

Getting Started

To build a third-party integration, you'll need OAuth 2.0 client credentials issued by Understory.

Contact us at integrations@understory.io with the following information.

After review, you will receive your client ID and secret key via a secure link and you can start building your integration.

OAuth 2.0 Authorization Code Grant

Third-party integrations use the OAuth 2.0 Authorization Code Grant flow. This is the industry-standard protocol for secure delegated authorization, used by platforms like Linear, Google, and Okta.

The flow consists of four main steps:

1. Redirect the user to Understory's authorization endpoint
2. Receive the authorization code via callback to your redirect URI
3. Exchange the code for access and refresh tokens
4. Use the access token to make API requests

Step 1: Initiate Authorization

Redirect the user to Understory's authorization endpoint to request access to their resources.

Include the following query parameters and remember to URL encode audience, redirect_uri, and scope.

https://api.auth.understory.io/oauth2/auth
  ?response_type=code
  &audience=https%3A%2F%2Fapi.understory.io
  &client_id=client-id
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &scope=offline+marketing.read
  &state=random-string

This will show a consent screen with your application name, logo, and the permissions being requested. If they approve, they will be redirected to your specified redirect URI.

Step 2: Handle the Callback

After the user authorizes your application, Understory redirects them to your redirect_uri with an authorization code:

https://example.com/callback
  ?code=AUTHORIZATION_CODE
  &state=random-string

If the user denies authorization or an error occurs, the callback will include error parameters instead. Read more in Error Handling.

https://example.com/callback
  ?error=access_denied
  &error_description=The+user+denied+the+request
  &state=random-string

Step 3: Exchange Code for Tokens

Exchange the authorization code for access and refresh tokens by making a POST request to the token endpoint https://api.auth.understory.io/oauth2/token. Use the following parameters provided in the body of the request.

curl -X POST https://api.auth.understory.io/oauth2/token \
  -H "User-Agent: My-Company/Marketing-Automation-App" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<client-id>" \
  -d "client_secret=<secret-key>" \
  -d "redirect_uri=https://example.com/oauth/callback" \
  -d "code=<authorization-code>"

If all parameters are valid you will receive the following response body with your token.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI0ZTUzZDkyLTY4ZmUt...",
  "expires_in": 3599,
  "refresh_token": "ory_rt_4dt-0JWm-9H2V4U1jfjUTCyJRbCZPSsvniMZQS18...",
  "scope": "offline marketing.read",
  "token_type": "bearer"
}

Step 4: Store Credentials Securely

After receiving the tokens, store them securely:

• Access tokens are short-lived (1 hour) and used to make API requests
• Refresh tokens are long-lived (30 days) and used to obtain new access tokens without requiring user re-authorization

Making API Requests

Include the access token in the Authorization header of your API requests.

curl -i -X GET \
  'https://api.understory.io/v1/marketing-consents?cursor=string&limit=100' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Refreshing Access Tokens

When an access token expires, use the refresh token to obtain a new one without requiring user interaction:

curl -X POST https://api.auth.understory.io/oauth2/token \
  -H "User-Agent: My-Company/Marketing-Automation-App" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<refresh-token>" \
  -d "client_id=<client-id>" \
  -d "client_secret=<secret-key>"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI0ZTUzZDkyLTY4ZmUt...",
  "expires_in": 3599,
  "refresh_token": "ory_rt_XOnJ6xdZlbAAPBSSJ91uoGSYwJ3DVBsKFL-GEM5O...",
  "scope": "offline marketing.read",
  "token_type": "bearer"
}

Error Handling

OAuth 2.0 errors follow the standard format defined in RFC 6749 Section 5.2:

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired"
}

Common errors include:

Testing Your Integration

To test your third-party integration during development:

1. Register development redirect URIs - When requesting credentials, include both production and development callback URLs (e.g., https://localhost:3000/oauth/callback for local testing).

2. Use a test Understory account - Create a separate Understory account specifically for testing. This allows you to authorize your app and test the OAuth flow without affecting real customer data.

3. Test the complete flow - Verify that your application can:

   • Redirect users to the authorization endpoint
   • Handle the callback with the authorization code
   • Exchange the code for tokens
   • Make API requests with the access token
   • Refresh tokens when they expire

4. Handle edge cases - Test scenarios like:

   • User denies authorization
   • Invalid or expired authorization codes
   • Expired access tokens
   • Network failures during token exchange

Further Reading

• Understory API Authentication - General authentication overview
• Understory API Reference
• OAuth 2.0 RFC 6749 - The OAuth 2.0 Authorization Framework
• OAuth 2.0 Security Best Practices - Current security recommendations
• What is the OAuth 2.0 Authorization Code Grant Type? - Introduction to the Authorization Code grant type