Authentication

To interact with the Kigo API, a partner authenticates requests with bearer session tokens. This guide describes the session types, how to obtain a partner-level session token, and how to handle expiration.

Session Types

Each endpoint's reference page lists the token it requires. User-level tokens are covered in User-Level Authentication.

Prerequisites

Kigo provides each partner with:

• Partner ID: A UUID that identifies your organization.
• API Key: A secret key for your organization.

A partner can obtain these values from their primary contacts at Kigo. Separate credentials are issued for the test and production environments.

Steps to Implement

1. Create a Partner-Level Session Token

   • Endpoint: Create a session token
   • Purpose: Authorizes partner-level endpoints, such as creating a user-level session token or an SSO session.
   • Token Expiration: 1 hour. There is no refresh for partner-level tokens; create a new one when it expires.
   Bash

   curl -X POST https://api.kigodigital.net/api/v1/auth/sessions \
     -H "Content-Type: application/json" \
     -d '{
       "partner_id": "<your partner id>",
       "api_key": "<your api key>"
     }'

   JSON

   {
     "token": "<partner-level session token>"
   }

   An unknown partner_id or incorrect api_key returns 400 with error_code invalid_input.

2. Use the Partner-Level Session Token

   • Header Example:

     Authorization: Bearer <partner-level session token>

Key Considerations

1. Handling Token Expiration: Partner-level session tokens expire after 1 hour. To maintain uninterrupted access to the API:
   • Token Renewal: Reuse the token across requests and create a new one before it expires.
   • Error Handling: A request with an expired or invalid partner-level token returns 401 with error_code authorization_error. Request a new token and retry the request.

Example Workflow

1. Obtain a partner-level session token with your Partner ID and API key.
2. Include the partner-level token in API requests to partner-level endpoints.
3. Renew the token before it expires to ensure continuous API access.

Best Practices for Authorization

• Secure Storage: Store the API key, Partner ID, and partner-level session tokens securely. Avoid hardcoding credentials in application code; use environment variables or a secrets vault. Never pass the API key or a partner-level session token to front-end clients.
• HTTPS Only: Always make API requests over HTTPS to ensure that tokens and other sensitive data are encrypted in transit.