User-Level Authentication

The Kigo API employs multiple levels of session tokens. To call endpoints on behalf of an individual member, a partner authenticates requests with a user-level session token. The same token is used by the Kigo Hub API and the Kigo Hub SDK. This guide describes how to obtain a user-level token, how to use it, and how to renew it.

Prerequisites

• A partner-level session token. See the API Authentication guide.
• The Partner API Key authentication method enabled for the program. If it is not enabled, the request returns 403 with error_code authorization_error.

Steps to Implement

1. Create a User-Level Session Token

   • Endpoint: Create account session
   • Authorization: The partner-level session token, as a bearer token.
   • Purpose: Authenticates requests that involve a specific member's actions or data.
   Bash

   curl -X POST https://api.kigodigital.net/api/v1/auth/sessions/accounts \
     -H "Authorization: Bearer <partner-level session token>" \
     -H "Content-Type: application/json" \
     -d '{
       "external_program_id": "<your external program id>",
       "external_user_id": "member-12345",
       "user_email": "[email protected]"
     }'

   JSON

   {
     "token": "<user-level session token>",
     "refresh_token": "<refresh token>",
     "account_id": "c5cbecd6-f6ea-4cfa-b2fc-dcd9fa81b519"
   }

   Field	Required	Description
   external_program_id	Yes	The program the member belongs to.
   external_user_id	Yes	Your stable identifier for the member. The member's Kigo account is keyed on this value within the program.
   user_email	No	The member's email address.
   user_attributes	No	Additional account attributes agreed with Kigo.

   The first time Kigo sees an external_user_id in a program, it creates the member's account. Later calls with the same external_user_id return a token for the same account.

2. Use the User-Level Session Token

   • Header Example:

     Authorization: Bearer <user-level session token>

Token Lifetimes

Renewing a User-Level Session Token

When the user-level session token expires, either create a new one with a partner-level token (step 1), or exchange the refresh token for a new session token without the partner-level token:

• Endpoint: Refresh account session

curl -X POST https://api.kigodigital.net/api/v1/auth/sessions/accounts/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "<refresh token>"
  }'

The response has the same shape as step 1: a new token, the same refresh_token, and the account_id. An invalid refresh token returns 401 with error_code authorization_error; create a new session with a partner-level token in that case.

Key Considerations

• Handling Token Expiration: A request with an expired or invalid user-level token returns an authentication error. Renew the token with the refresh token, or create a new one, and retry the request.

Example Workflow

1. Obtain a partner-level session token using the API Authentication guide.
2. Create a user-level session token for the member the application needs to act for.
3. Include the user-level token in API requests to access member-specific resources.
4. Renew the token with the refresh token, or create a new one, when it expires.

Best Practices for Authorization

• HTTPS Only: Always make API requests over HTTPS to ensure that tokens and other sensitive data are encrypted in transit.
• Pass to the Client: User-level session tokens are scoped to a single member, so they are safe to pass to that member's client. Create them only after the member has signed in to your application and proved they are authorized to access their Kigo-powered experience.
• Protect the Refresh Token: The refresh token is long-lived. Store it as securely as any other credential.