Authentication

Overview

POS Hub uses OAuth2 for authentication and authorization. This guide provides an overview of the authentication process, including how to obtain access tokens, refresh tokens.

Authentication Flows

The POS Hub API supports multiple authentication flows to accommodate different use cases:

Client Credentials Grant

Overview

The client credentials grant is used when applications need to authenticate themselves rather than a user. This is the primary authentication method for server-to-server communication and automated processes. Applications use this grant to perform actions on locations they have been authorized for, such as creating orders, updating products, or retrieving menus.

When to Use Client Credentials

• Server-to-server communication: Backend services that need API access
• Automated processes: Scheduled tasks, webhooks, or batch operations
• Application-level actions: Operations not tied to a specific user
• Production integrations: Most third-party applications use this grant

Implementation Flow

Request Parameters

Parameter	Required	Description
grant_type	Yes	Must be client_credentials
client_id	Yes	Your application's client identifier
client_secret	Yes	Your application's client secret
scope	No	Requested scopes (space-separated)

Example Request

curl -X POST https://api.tryposhub.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=orders.read orders.write"

Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def50200a1b2c3d4e5f6789012345678...",
  "token_type": "Bearer",
  "expires_in": 1234567,
  "scope": "orders.read orders.write"
}

Important Considerations

• Token expiration: Access tokens have extended lifespans (check expires_in field in response)
• Location access: Tokens only provide access to locations where your application is installed
• Scope limitations: You can only request scopes that your application has been granted
• Security: Store client credentials securely, never expose them in client-side code
• Refresh tokens: Use refresh tokens to obtain new access tokens before expiration

Authorization Code Grant

Overview

The authorization code grant is the standard OAuth2 flow for user authorization and application onboarding. This secure redirect-based process allows users to grant your application access to specific POS Hub locations without sharing their credentials. It's the recommended flow for web applications and mobile apps that need user-level permissions.

When to Use Authorization Code Grant

• Application onboarding: When users need to connect their POS Hub account to your application
• User-level permissions: Accessing data with the same permissions as the authenticated user
• Web applications: Browser-based applications with server-side components
• Mobile applications: Native apps that can handle redirects
• Third-party integrations: External applications requiring user consent

Implementation Flow

Authorization Request Parameters

Step 1: Redirect to Authorization URL

Parameter	Required	Description
client_id	Yes	Your application's client identifier
redirect_uri	Yes	URL where user will be redirected after authorization
scope	Yes	Requested permissions (space-separated)
response_type	Yes	Must be code
state	Recommended	Random string to prevent CSRF attacks

Token Exchange Parameters

Step 2: Exchange Code for Token

Parameter	Required	Description
grant_type	Yes	Must be authorization_code
code	Yes	Authorization code received from redirect
client_id	Yes	Your application's client identifier
client_secret	Yes	Your application's client secret
redirect_uri	Yes	Same redirect URI used in authorization request

Example Authorization Request

# Redirect user to this URL
https://api.trypos hub.com/oauth2/authorize?client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=orders.read orders.write&response_type=code&state=random_string

Example Token Exchange Request

curl -X POST https://api.trypos hub.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=received_auth_code&client_id=your_client_id&client_secret=your_client_secret&redirect_uri=https://yourapp.com/callback"

Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def50200a1b2c3d4e5f6789012345678...",
  "token_type": "Bearer",
  "expires_in": 1234567,
  "scope": "orders.read orders.write"
}

Important Considerations

• User permissions: Access tokens inherit the permissions of the authenticated user
• Short-lived codes: Authorization codes have limited lifespans and can only be used once
• Redirect URI validation: Must exactly match the URI registered with your application
• State parameter: Always use state parameter to prevent CSRF attacks
• HTTPS required: Redirect URIs must use HTTPS in production
• Token expiration: Check expires_in field in response and use refresh tokens for renewal

Password Grant

Overview

The password grant allows direct authentication using a username and password. This grant is exclusively for POS Hub first-party applications and is not available to external applications or partners. It enables trusted applications to authenticate users directly without requiring redirects, providing a streamlined experience for internal POS Hub platform applications.

When to Use Password Grant

• First-party applications only: Internal POS Hub applications and services
• Trusted environments: Applications where POS Hub controls both the client and server
• Direct authentication: When redirect-based flows are not suitable
• Internal tooling: Administrative tools and internal dashboards

Note: This grant requires special authorization from the POS Hub team and is not available for third-party developers.

Implementation Flow

Request Parameters

Parameter	Required	Description
grant_type	Yes	Must be password
username	Yes	The user's username or email
password	Yes	The user's password
client_id	Yes	Your application's client identifier
client_secret	Yes	Your application's client secret
scope	No	Requested scopes (space-separated)

Example Request

curl -X POST https://api.trypos hub.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=user@example.com&password=user_password&client_id=your_client_id&client_secret=your_client_secret&scope=orders.read orders.write"

Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def50200a1b2c3d4e5f6789012345678...",
  "token_type": "Bearer",
  "expires_in": 1234567,
  "scope": "orders.read orders.write"
}

Important Considerations

• Internal use only: Not available to external developers or partners
• User permissions: Access tokens inherit the exact permissions of the authenticated user
• Credential security: Must handle user credentials with extreme care
• Authorization required: Requires explicit approval from POS Hub team
• Token expiration: Check expires_in field in response for token lifetime
• Scope inheritance: Granted scopes limited by user's actual permissions

Refresh Token Grant

Overview

The refresh token grant allows applications to obtain new access tokens without requiring users to re-authenticate. This is essential for maintaining uninterrupted API access when access tokens expire. All POS Hub authentication flows provide refresh tokens, enabling seamless token renewal and continuous application operation.

When to Use Refresh Tokens

• Access Token Expiration: When your current access token expires (check expires_in field for timing)
• Proactive Refresh: Before the access token expires to ensure uninterrupted service
• Error Recovery: When receiving 401 Unauthorized responses due to token expiration
• Continuous Operation: For long-running applications that need persistent API access

Token Lifecycle

1. Initial Authentication: Authenticate using any grant type to receive both access_token and refresh_token
2. Access Token Usage: Use the access token for API requests until it expires
3. Refresh Process: Use the refresh token to obtain a new access token before or after expiration
4. Token Rotation: Each refresh provides a new access token and refresh token pair

Implementation Flow

Request Parameters

Parameter	Required	Description
grant_type	Yes	Must be refresh_token
refresh_token	Yes	The refresh token received from previous authentication
client_id	Yes	Your application's client identifier
client_secret	Yes	Your application's client secret
scope	No	Requested scopes (must be subset of original)

Example Request

curl -X POST https://api.trypos hub.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=your_refresh_token_here&client_id=your_client_id&client_secret=your_client_secret"

Example Response

{
  "access_token": "new_access_token_here",
  "refresh_token": "new_refresh_token_here",
  "token_type": "Bearer",
  "expires_in": 1234567,
  "scope": "orders.read orders.write menu.read"
}

Error Responses

Expired Refresh Token (400)

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, or does not match the redirection URI"
}

Invalid Client Credentials (401)

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Important Considerations

• Token Rotation: Each successful refresh invalidates the old refresh token and issues a new one
• Single Use: Refresh tokens can only be used once - always store the new refresh token
• Scope Limitations: Cannot request scopes that weren't in the original access token
• Expiration: Refresh tokens have limited lifespans and cannot be used after expiration
• Security: Store refresh tokens securely and never expose them in client-side code
• Concurrent Requests: Implement locking to prevent multiple simultaneous refresh requests