Skip to main content

Authentication

The Supatool API uses OAuth2/OIDC for authentication. All API requests (except public endpoints) require a valid session token.

Overview​

To access protected endpoints, you need to:

  1. Authenticate through the OIDC flow to obtain session tokens
  2. Include the session token in API requests using the Authorization header
  3. Include the session ID using the X-Session-ID header

Authentication Flow​

Step 1: Obtain Session Tokens​

Users authenticate through the OIDC authorization flow. After successful authentication, you'll receive:

  • Session Token: A bearer token for API authentication
  • Session ID: An identifier for the session

Step 2: Make Authenticated Requests​

Include both the session token and session ID in your API requests:

curl -X POST https://api.supatool.com/api.v1.APIService/GetTenant \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "X-Session-ID: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "example"}'

Headers​

Required Headers​

  • Authorization: Bearer <session-token>

    • The session token obtained after authentication
    • Must be prefixed with "Bearer "

  • X-Session-ID: <session-id>

    • The session identifier
    • Required alongside the Authorization header

Example​

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-Session-ID: 12345678-1234-1234-1234-123456789abc
Content-Type: application/json

Public Endpoints​

The following endpoints do not require authentication:

  • GetHealth - Health check endpoint
  • GetTenant - Get tenant information by subdomain
  • GetPublishedDocument - Get published document
  • GetPublishedDocumentBySlug - Get published document by slug
  • GetPublishedFormBySlug - Get published form by slug
  • SubmitForm - Submit a form
  • GetFormByPreviewToken - Get form by preview token
  • Analytics ingestion endpoints

Error Responses​

401 Unauthorized​

Returned when:

  • Missing Authorization header
  • Invalid or expired session token
  • Missing X-Session-ID header
  • Session validation failed
{
  "error": "invalid session"
}

OAuth2 Scopes​

When authenticating, the following scopes are available:

  • openid - OpenID Connect scope
  • profile - User profile information
  • email - User email address

Best Practices​

  1. Store tokens securely: Never commit session tokens to version control
  2. Handle token expiration: Implement token refresh logic
  3. Use HTTPS: Always use HTTPS in production
  4. Validate responses: Check for 401 errors and handle re-authentication

Getting Started​

To get started with the API:

  1. Set up OAuth2/OIDC authentication for your application
  2. Complete the authorization flow to obtain session tokens
  3. Use the session token and session ID in your API requests

For more information about setting up authentication, contact your account administrator or refer to your tenant's authentication configuration.