Partner API Key

Introduction

With the Partner API Key method, your server vouches for the member. The member signs in to your website or app as they normally do. When they choose to open the Kigo experience, your server calls the Kigo API to create an SSO session for that member, and your application sends the member to the Kigo-hosted experience with the session ID.

This is the simplest method if you already have a member login and a back-end server. It needs no Identity Provider and no IdP configuration.

Authentication Flow

sequenceDiagram
    actor Member
    participant App as Your Web App
    participant Server as Your Server
    participant Kigo as Kigo API
    participant Exp as Kigo-hosted Experience

    Member->>App: Signs in to your site, clicks link to Kigo experience
    App->>Server: Request a Kigo session for this member
    Server->>Kigo: POST /api/v1/auth/sessions (api_key, partner_id)
    Kigo-->>Server: Partner-level token (60 min)
    Server->>Kigo: POST /api/v1/accounts/sso-sessions (Bearer token)
    Kigo-->>Server: session_id (30 min)
    Server-->>App: session_id
    App->>Exp: Redirect to {base_url}/sso/{external_program_id}?uuid={session_id}
    Exp->>Kigo: Exchange session_id
    Exp-->>Member: Member is signed in

What Kigo Provides

Separate credentials are issued for the test and production environments.

What You Provide

Steps to Implement

Step 1: Create a Partner-Level Session Token

From your server, exchange your API key for a partner-level token. See the API Authentication Guide for details.

• Endpoint: Create an API session token
• Token lifetime: 60 minutes. Reuse the token across requests and request a new one before it expires.

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>"
  }'

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

Step 2: Create an SSO Session for the Member

Using the partner-level token, create an SSO session for the member who is signed in to your site.

• Endpoint: Create an SSO session for a user
• Session lifetime: 30 minutes.

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

{
  "session_id": "6f1c2b7e-3a0d-4c1e-9b8a-2d5f7e9c1a34"
}

Request Fields

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

Step 3: Send the Member to the Kigo Experience

Return the session_id to your application and redirect the member (or load an iframe) to:

{base_url}/sso/{external_program_id}?uuid={session_id}

For example:

https://<base_url>/sso/<external_program_id>?uuid=6f1c2b7e-3a0d-4c1e-9b8a-2d5f7e9c1a34

The Kigo-hosted experience exchanges the session ID and signs the member in.

📘

Base URL and path

The base URL and path depend on which Kigo-hosted experience your program uses. Once you are able to create a session ID, contact your Kigo account manager for the base URL and path for your program in test and production.

Example Server Route

An illustrative Node.js route. Your implementation may differ.

// GET /kigo/launch — called when a signed-in member clicks "Go to rewards"
app.get("/kigo/launch", requireMemberLogin, async (req, res) => {
  const KIGO_API = "https://api.kigodigital.net";

  // 1. Partner-level token (cache this for up to 60 minutes in production)
  const auth = await fetch(`${KIGO_API}/api/v1/auth/sessions`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      partner_id: process.env.KIGO_PARTNER_ID,
      api_key: process.env.KIGO_API_KEY,
    }),
  }).then((r) => r.json());

  // 2. SSO session for this member
  const sso = await fetch(`${KIGO_API}/api/v1/accounts/sso-sessions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${auth.token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_program_id: process.env.KIGO_EXTERNAL_PROGRAM_ID,
      external_user_id: req.member.id,
      user_email: req.member.email,
      is_single_use: true,
    }),
  }).then((r) => r.json());

  // 3. Send the member to the Kigo experience (base URL from your account manager)
  res.redirect(
    `${process.env.KIGO_EXPERIENCE_BASE_URL}/sso/${process.env.KIGO_EXTERNAL_PROGRAM_ID}?uuid=${sso.session_id}`
  );
});

Errors

If the session ID has expired (after 30 minutes) or a single-use session ID was already used, the member is not signed in. Create a new session ID each time the member launches the experience.

Key Considerations

• Program setup: Use the external_program_id Kigo gives you. Programs, branding, and SSO enablement are configured by Kigo with you before launch. Contact your account manager to add a program.
• Stable member IDs: The account is keyed on external_user_id. If that value changes for a member, Kigo treats them as a new member.
• Create sessions on demand: Create the session ID when the member clicks through, not ahead of time. It expires after 30 minutes.
• Single use: Set is_single_use to true so a session ID cannot be replayed. Use false only if the session must be reused in a trusted environment where client-side storage is not possible.

Best Practices

• Keep credentials on the server: The API key and partner-level token must never be sent to a browser or mobile app. Store them in environment variables or a secrets manager.
• Only create sessions for authenticated members: Your server is vouching for the member's identity. Create a session only after the member has signed in to your site.
• Cache the partner-level token: Reuse it for up to 60 minutes, and refresh it when Kigo returns 401.
• HTTPS only: Make all calls to Kigo over HTTPS.