The Avvail Guest Book API uses OAuth 2.0 with the Client Credentials flow to secure access. This approach is ideal for server-to-server communications, where your application requests an access token using a Client ID and Client Secret.

Overview

1. Obtain Your Credentials — request a Client ID and Client Secret from our support team. Typically, you'll receive sandbox credentials first, then production credentials when you're ready.
2. Request an Access Token — send a POST request to the relevant token URL.
3. Use the Access Token — include the token in the Authorization header when calling the API.

Client Credentials

When integrating with the Guest Book API, you will be provided with:

• Client ID: A unique identifier for your application. This value is public and is used to identify your application during the OAuth flow.
• Client Secret: A confidential value that must be kept secure. This secret is used in conjunction with your Client ID when obtaining an access token.

Important: Always store your Client Secret in a secure, encrypted location, and never log it in plaintext.

Access Tokens

Requesting Tokens

Tokens are granted via the OAuth 2.0 Client Credentials flow. Send a POST request to the relevant token URL:

• Sandbox: https://sandbox.auth.avvail.com/oauth/token
• Production: https://auth.avvail.com/oauth/token

Request Example

curl -X POST https://auth.avvail.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.avvail.com/",
    "grant_type": "client_credentials"
  }'

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "reservations:read",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Verifying Tokens

Each access token is a JWT (JSON Web Token) containing standard OAuth 2.0 claims. A decoded token looks like:

{
  "iss": "https://auth.avvail.com/",
  "sub": "xRt7hZmGvA9KsL2Dy5EbXfJ8iNqW3uP6@clients",
  "aud": "https://api.avvail.com/",
  "iat": 1677721600,
  "exp": 1677807600,
  "scope": "reservations:read venues:read availability:read",
  "gty": "client-credentials",
  "azp": "xRt7hZmGvA9KsL2Dy5EbXfJ8iNqW3uP6"
}

Verify the token's signature using the JSON Web Key Set (JWKS) at https://auth.avvail.com/.well-known/jwks.json. Use a standard JWT library to perform RS256 signature validation.

Using Tokens

Include the token in the Authorization header for every API request:

Authorization: Bearer <ACCESS_TOKEN>

Refreshing Tokens

Tokens are not refreshable via a refresh token. Request a new token using the same Client ID and Client Secret before the current token expires. If your application runs continuously, schedule a refresh before expiration to avoid interrupted service.

Token Expiration

By default, tokens expire 24 hours after issuance. If you need a shorter token duration, contact our support team to adjust the default settings.

Scopes

API credentials are issued with specific scopes that determine which endpoints are accessible. The v2 API supports the following scopes:

Contact your account manager to adjust the scopes assigned to your credentials.

Security Best Practices

• Use Secure Storage: Store the Client Secret and access tokens in a secure, encrypted location (e.g., environment variables or a secrets manager). Do not commit them to source control or include them directly in application code.
• Never Log Secrets or Tokens in Plaintext: Avoid printing the Client Secret or access tokens to logs. If logging is necessary for debugging, redact or mask the critical parts (e.g., only log the first 4 and last 4 characters).
• Verify and Monitor: Verify all access tokens and monitor API usage to detect suspicious activity. If you suspect credentials have been leaked, rotate them immediately.