support Contact support
    • Kamino
    • Developers
    • Kamino platform API integration
    • Get started with Kamino platform API integration

    Connect to Kamino platform APIs

    Table of Contents

    Overview Authentication overview High-level authentication flow Token types Access token (short-lived) Key characteristics Refresh token (long-lived) Authentication endpoints Step-by-step authentication workflow Step 1: Generate an access token using credentials Step 2: Create a refresh token Step 3: Generate a session access token Step 4: Call Kamino APIs Step 5: Revoke a token (optional) Additional authentication resources Security best practices

    Overview

    This guide explains how authentication works on the Kamino platform, the purpose of each token, and the recommended workflow to securely connect your application to Kamino APIs.

    Kamino APIs rely on a three-step authentication flow designed to balance security, token rotation, and developer experience.

    Authentication overview

    The platform uses two types of tokens generated through three distinct steps:

    Token Purpose Lifetime How it is obtained
    Access Token Session token used to call all Kamino APIs. Short-lived
    • Generated once using credentials.
    • Generated using a refresh token.
    Refresh Token Long-lived token used to refresh sessions. Up to 48 hours Generated using an access token

    Only access tokens can be used to call Kamino business APIs. Refresh tokens are never used directly to call business APIs.

     

    High-level authentication flow

    1. Authenticate using Equativ-provided credentials to fetch an access token.
    2. Create a refresh token using your access token.
    3. Generate access tokens as needed via your refresh token.
    4. Connect to Kamino business APIs.

    Token types

    Access token (short-lived)

    An access token is a short-lived bearer token used to authenticate requests to Kamino APIs.

    You can obtain it in two different ways, depending on the stage of your integration:

    How it is generated Purpose
    Using Equativ-provided credentials Initial authentication and setup
    Using a refresh token Ongoing API usage and session renewal

    Key characteristics

    • It’s short-lived.
    • You must include it in the Authorization header: Authorization: Bearer <ACCESS_TOKEN>.
    • It’s required for all Kamino API calls.
    • You can rotate it at any time.
    • It’s safe to generate frequently.

    Although access tokens can be generated via different endpoints, they behave the same way once issued.

    Refresh token (long-lived)

    A refresh token is a long-lived credential associated with your Kamino account.

    It’s used only to generate new access tokens without reusing credentials.

    • It’s valid up to 48 hours.
    • The system returns it only once.
    • You must store it securely.
    • You must never use it directly to call business APIs.

    Authentication endpoints

    Method Endpoint Description Docs
    POST https://api.kaminoretail.dev/auth/getToken Generate an access token using credentials Get access token
    POST https://api.kaminoretail.dev/auth/me/tokens Create a refresh token Create token
    GET https://api.kaminoretail.dev/auth/refresh-token Generate a session access token using a refresh token Create access token
    DELETE https://api.kaminoretail.dev/auth/me/tokens/{token_id} Revoke a given token Revoke token 

    Step-by-step authentication workflow

    Step 1: Generate an access token using credentials

    Use this step during initial setup.

    POST /auth/getToken
    • Returns a credentials-based access token.
    • It’s short-lived.
    • Uses credentials provided by Equativ.

    Step 2: Create a refresh token

    POST /auth/me/tokens
Authorization: Bearer <ACCESS_TOKEN>
    • Returns a refresh token.
    • The system shows the token only once.
    • Store it securely.

    Step 3: Generate a session access token

    GET /auth/refresh-token
Authorization: Bearer <REFRESH_TOKEN>
    • Returns a session access token.
    • It’s valid for the lifetime of the session.
    • The endpoint is rate limited.

    Step 4: Call Kamino APIs

    Authorization: Bearer <SESSION_ACCESS_TOKEN>

    Step 5: Revoke a token (optional)

    DELETE /auth/me/tokens/{token_id}

    Immediately invalidates any token, which makes it unusable.

    Additional authentication resources

    For more information, see Business API V3.

    Security best practices

    • Never expose credentials or refresh tokens in frontend code.
    • Rotate refresh tokens regularly.
    • Revoke tokens immediately if they become compromised.
    • Use a secrets manager for all credentials.

    RELATED ARTICLES