Right-Hand API Integration Guide
Right-Hand provides API access that allows customers to securely integrate their systems with the Right-Hand platform.
For API integrations, Right-Hand will provide:
An Admin Token
A Service Account API credential
These credentials are used to obtain an authentication token before interacting with other Right-Hand APIs.
The recommended integration flow is:
Admin Token + Service Account API → Authentication Token → API Requests →
Destroy Authentication Token
For the complete API reference, request formats, and supported operations, refer to the Right-Hand API Documentation.
Prerequisites
Before starting the integration, ensure that you have:
An active Right-Hand account
API access enabled for your organization
An Admin Token provided by Right-Hand
A Service Account API credential provided by Right-Hand
Access to the Right-Hand API documentation
A secure method for storing credentials
The Admin Token and Service Account API credential are sensitive credentials and should only be accessible to trusted backend systems.
Step 1: Securely Store the Credentials
Right-Hand will provide the Admin Token and Service Account API credential required for your integration.
These credentials should be securely stored using a secrets-management solution or encrypted environment variables.
Do not expose these credentials in:
Front-end applications
Browser-based scripts
Mobile applications
Public source-code repositories
Application logs
Screenshots or support tickets
These credentials should only be used by a trusted server-side application.
Step 2: Obtain an Authentication Token
Before making requests to other Right-Hand APIs, your application must first obtain an Authentication Token.
Use the Admin Token and Service Account API credential with the Right-Hand authentication API.
Refer to the following documentation for the authentication process:
The authentication API returns a token that should be used to authorize subsequent API requests.
Your application should obtain this token at the beginning of the API operation or integration workflow.
Step 3: Use the Authentication Token for Subsequent Requests
Once the authentication token has been obtained, use it for subsequent Right-Hand API requests.
The token should be supplied using the standard Bearer authorization format:
Authorization: Bearer <authentication_token>
The authentication token should be used instead of sending the Admin Token or Service Account credentials with each API request.
A typical request flow is therefore:
Authenticate
↓
Receive Authentication Token
↓
Use Authentication Token for API Requests
The individual APIs, parameters, and response formats are documented in the Right-Hand API Documentation.
Step 4: Complete the Required API Operations
After authentication, your application can perform the required operations using the APIs available to your organization.
The same authentication token can be used for the subsequent requests that form part of the current integration workflow.
For example:
Authenticate
→ Receive Authentication Token
→ API Request
→ Additional API Request
→ Additional API Request
→ Operation Complete
Your integration should retain the authentication token only for as long as it is required to complete the operation.
Step 5: Destroy the Authentication Token
Once the required API operations are complete, the authentication token should be destroyed.
Use the Right-Hand token-destruction API documented here:
Destroying the authentication token ensures that the temporary token can no longer be used after the integration operation has completed.
The complete lifecycle should therefore be:
1. Obtain Authentication Token
↓
2. Use Token for Subsequent API Requests
↓
3. Complete Integration Operation
↓
4. Destroy Authentication Token
Recommended Integration Pattern
Right-Hand recommends treating authentication tokens as short-lived credentials tied to an individual integration workflow.
The recommended pattern is:
Your Backend Application
↓
Admin Token + Service Account API credential stored securely
↓
Request Authentication Token
↓
Receive Authentication Token
↓
Use Bearer Token for Right-Hand API Requests
↓
Complete Required Operations
↓
Destroy Authentication Token
This approach limits the lifetime of the authentication token and reduces the risk associated with credentials remaining active after they are no longer required.
Security Recommendations
When integrating with the Right-Hand API:
Store the Admin Token and Service Account credentials in a secure secrets-management system.
Never commit credentials or tokens to source control.
Never expose credentials in client-side applications.
Do not include authentication tokens in application or debugging logs.
Restrict access to API credentials using least-privilege controls.
Use HTTPS for all API communication.
Destroy authentication tokens after completing the required operation.
Obtain a new authentication token for future API operations.
Rotate the Admin Token or Service Account credentials if you believe they have been exposed.
Handling Authentication Failures
Your integration should handle authentication-related failures gracefully.
Authentication request fails
Verify that:
The Admin Token is correct.
The Service Account API credential is correct.
The credentials have not been revoked or replaced.
The request follows the format documented in the Authentication API.
Refer to:
Subsequent API requests return an authentication error
Verify that:
The authentication token is included in the request.
The request uses the correct Bearer authorization format.
The token has not already been destroyed or invalidated.
If the token is no longer valid, obtain a new authentication token before continuing.
Token destruction fails
Verify that the token and request are being supplied according to the token-destruction API documentation.
Refer to:
Authentication Flow Summary
The complete integration lifecycle is:
Right-Hand provides Admin Token + Service Account API credential
↓
Integration requests an Authentication Token
↓
Right-Hand returns an Authentication Token
↓
Integration uses the token as a Bearer Token
↓
Integration performs the required API requests
↓
Integration destroys the Authentication Token
↓
Authentication Token is no longer used
For each new API workflow, repeat the authentication lifecycle beginning with obtaining a new authentication token.
API Reference
For authentication details, supported APIs, parameters, request formats, and response structures, refer to the Right-Hand API documentation.
Authentication
End of Session
If you require API credentials or assistance configuring your integration, contact the Right-Hand support team.