Guides

SpotOn OAuth - Integration Guide

Suggest Edits

Overview

This document outlines the integration process for partners implementing the "SpotOn OAuth" feature. This OAuth2-based authentication allows users to access their SpotOn location data within partner applications, streamlining the onboarding process and data retrieval.

Authentication Flow

The integration uses a standard OAuth2 flow with two distinct token types:

  1. User Authentication Token (authorization_code)

    • User-specific authentication
    • 1-hour expiration period
    • Used for location onboarding

  2. Service Authentication Token (client_credentials)

    • Application-level authentication
    • 24-hour expiration period
    • Used for accessing data from onboarded locations

Onboarding Flow Diagram

Onboarding Flow Diagram

Implementation Steps

1. Initial Setup

To get started, you'll need to request the following credentials from SpotOn:

  • Client ID
  • Client Secret
  • Authorization endpoint URL
  • Token endpoint URL

2. User Authentication Flow

Step 1: Redirect to Authorization Page

GET https://api.spoton.com/oauth2/v1/authorize

Required Parameters:

  • client_id: Your application's client ID
  • response_type: Set to "code"
  • redirect_uri: Your application's callback URL
  • scope: You must include all scopes SpotOn has granted your client
  • state: Random string to prevent CSRF attacks
  • prompt: Must be set to "consent" to ensure users are prompted for all consent-enabled scopes

Important Note

The prompt=consent parameter is mandatory and ensures proper consent handling. When included in the authorization request, users are prompted for all consent-enabled scopes, including both required and optional scopes, even when the user has already given consent for a scope or skipped a scope previously.

Step 2: Handle the Callback

After the user authenticates, SpotOn will redirect to your redirect_uri with:

  • code: Authorization code
  • state: The same state value you provided

Step 3: Exchange Code for Token

POST https://api.spoton.com/oauth2/v1/token

Required Headers:

  • authorization: Basic ENCODED_CREDENTIALS where ENCODED_CREDENTIALS is your {{client_id}}:{{client_secret}} base64-encoded

Required Parameters:

  • grant_type: "authorization_code"
  • code: The authorization code received
  • redirect_uri: Must match the original redirect URI

Response:

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "eyJraWQiOiJqZEh2VUFkSHlhb3BVa2dZc0tnWVpzaHQ5QkgwQ1RnTXNpRVdzSG1uRTE4IiwiYWxnIjoiUlMyNTYifQ...",
  "scope": "menu:all:read"
}

3. Service Authentication Flow

To obtain a service token for accessing onboarded locations:

POST https://api.spoton.com/oauth2/v1/token

Required Headers:

  • authorization: Basic ENCODED_CREDENTIALS where ENCODED_CREDENTIALS is your {{client_id}}:{{client_secret}} base64-encoded

Required Parameters:

  • grant_type: "client_credentials"
  • scope: A comma-separated list of all scopes desired. May not be empty. You may only include scopes SpotOn has granted your client.

Response:

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "service_jwt_token",
  "scope": "menu:all:read"
}

Location Management

Retrieving Available Locations

To get the list of locations associated with the authenticated user:

GET https://api.spoton.com/onboarding/v1/location-candidates

Headers:

  • Authorization: Bearer {user_access_token}

Response:

{
  "candidates": [
    {
      "location_id": "BL-ABCD-EFGH-IJKL",
      "name": "Joe's Pizza",
      "address": {
        "address_line_1": "123 Main St",
        "address_line_2": "Suite 100",
        "city": "Springfield",
        "state": "IL",
        "postal_code": "62704",
        "country": "US"
      },
      "eligible": true,
      "ineligible_reason": ""
    }
  ]
}

Onboarding a Location

To onboard a location to your application:

POST https://api.spoton.com/onboarding/v1/location-onboard

Headers:

  • Authorization: Bearer {user_access_token}
  • Content-Type: application/json

Request Body:

{
  "location_id": "BL-ABCD-EFGH-IJKL"
}

Response:

{
  "onboarded_location": {
    "id": "18af2efd-fbe2-463f-9a0d-0482b671da32",
    "status": "ONBOARDING_STATUS_ACTIVE",
    "onboarded_at": "2025-05-01T00:00:00Z"
  }
}

Accessing Location Data

After successful onboarding, use the service token to access location data through SpotOn's various APIs. The specific endpoints and data available will depend on your integration agreement and the scopes granted. Your application cannot access any SpotOn location that has not granted access to your application through Sign In With SpotOn.

Example data access:

GET https://api.spoton.com/{service_name}/{api_version}/{endpoint}

Headers:

  • Authorization: Bearer {service_access_token}

Refer to your specific API documentation for available endpoints and data structures.

Important Notes

  1. User access tokens expire after 1 hour and cannot be refreshed.
  2. Service access tokens expire after 24 hours.
  3. SpotOn currently operates in the US only and may block traffic from other locations.
  4. Each user can only onboard locations they have access to within SpotOn.
  5. Locations have eligibility requirements - check the eligible field before attempting to onboard.
  6. Available scopes are listed below. Based on the nature of your business and integration needs, a subset of these scopes will be assigned to your application. Additional scopes might be available as per your specific integration agreement.
    • business:all:read: Read-only access to all business endpoints with read-operations
    • loyalty:all:read: Read-only access to loyalty endpoints with read-operations
    • loyalty:all:write: Full access to all loyalty endpoints
    • loyalty:status:read: Read-only access to loyalty status information
    • menu:all:read: Read-only access to all menu endpoints
    • order:submit:override: Orders submitted with this scope do not need to be signed
    • order:submit:write: Orders submitted with this scope must be signed
    • reporting:orders:read: Read-only access to order reporting endpoints
    • labor:all:read: Read-only access to all labor endpoints with read-operations
  7. During the "Sign In With SpotOn" process, the user will be required to consent to all scopes assigned to your partner application.

Code Libraries

You can find compatible OAuth 2.0 client libraries for various programming languages at https://oauth.net/code/.

Best Practices

  1. Token Management

    • Store tokens securely (e.g., encrypted in your database)
    • Implement token regeneration logic since refresh tokens are not provided
    • Handle token expiration gracefully by requesting new tokens when needed

  2. Error Handling

    • Implement comprehensive error handling for all API calls
    • Provide clear error messages to users
    • Log authentication failures for security monitoring

  3. User Experience

    • Minimize the number of authorization requests
    • Provide clear instructions during the authorization flow
    • Implement a clean UI for location selection

  4. Security

    • Always use HTTPS for all API calls
    • Implement CSRF protection using the state parameter
    • Follow OAuth security best practices

Support

For additional assistance, contact SpotOn Partner Support at [email protected].

Updated 7 months ago