The JWT access token

An Outseta JWT Access Token identifies an authenticated user of your app. It can be decoded to access the payload (aka, information about the user).

How to access the JWT Access Token

Client-side with JavaScript

There are several ways to access the JWT Access Token and its decoded payload on your site:

Listen for the accessToken.set event — Triggered when the access token is set, automatically decodes it for you:

Outseta.on("accessToken.set", function(decodedPayload) {
  console.log("Person Uid:", decodedPayload.sub);
  console.log("Account Uid:", decodedPayload["outseta:accountUid"]);
});

Get the decoded payload directly — Returns the currently stored JWT payload:

const payload = Outseta.getJwtPayload();

if (payload) {
  console.log("Person Uid:", payload.sub);
  console.log("Email:", payload.email);
  console.log("Account Uid:", payload["outseta:accountUid"]);
}

Get the encoded access token — Returns the raw JWT string for use in API requests:

const accessToken = Outseta.getAccessToken();

// Use in Authorization header for API requests
fetch("https://your-api.com/endpoint", {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

👉 How to retrieve user info client-side with JavaScript

Server-side with the API

You can generate access tokens server-side using the /tokens endpoint. This is useful for backend integrations or when you need to authenticate users programmatically.

With username and password:

const response = await fetch("https://<your-domain>.outseta.com/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  body: new URLSearchParams({
    username: "[email protected]",
    password: "user-password"
  })
});

const data = await response.json();
const accessToken = data.access_token;

With API keys:

const response = await fetch("https://<your-domain>.outseta.com/tokens", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Outseta <api-key>:<secret-key>"
  },
  body: new URLSearchParams({
    username: "[email protected]"
  })
});

const data = await response.json();
const accessToken = data.access_token;

⚠️ Important: Always call the /tokens endpoint from your server. Never expose usernames, passwords, or API keys on the client side.

👉 Generate JWT Access Tokens (aka. log in users) using the Outseta API
👉 Decode and verify Outseta JWT Access Tokens server-side

The decoded payload

{
  "nbf": 1610374706,
  "exp": 1610979506,
  "iss": "http://go.outseta.com",
  "client_id": "go.outseta.com.resource-owner",
  "scope": [
    "openid",
    "outseta",
    "profile"
  ],
  "sub": "3wQXdmKz",
  "auth_time": 1610374706,
  "idp": "idsrv",
  "email": "[email protected]",
  "email_verified": true,
  "family_name": "Name",
  "given_name": "First",
  "name": "First Last",
  "nameid": "3wQddmKz",
  "outseta:accountUid": "wZmNddO",
  "outseta:accountClientIdentifier": "1",
  "outseta:isPrimary": "0",
  "outseta:subscriptionUid": "dpWr3mnq",
  "outseta:planUid": "y7maddEq",
  "outseta:addOnUids": [
    "y7marQEq",
    "2amRZEmJ"
  ],
  "amr": [
    "password"
  ],
  "outseta:iss": "go.outseta.com",
  "aud": "go.outseta.com",
  "iat": 1706027112
}

Key fields explained

Here are the most important fields you'll use when working with Outseta JWT tokens:

Person (User) Information

• sub - The Person Uid (unique identifier for the person). This is the primary way to identify which person is authenticated. It will always be the same for the same person.
• email - The person's email address
• name - The person's full name (combines given_name and family_name)
• given_name - The person's first name
• family_name - The person's last name
• email_verified - Boolean indicating if the email has been verified

Account & Subscription Information

These fields are prefixed with outseta: and provide information about the person's account and subscription:

• outseta:accountUid - The Account Uid this person belongs to. In Outseta, people belong to accounts, and accounts have subscriptions. It will always be the same for the same account.
• outseta:isPrimary - Whether this person is the primary contact for the account (returns "0" or "1" as a string)
• outseta:subscriptionUid - The Uid of the account's current subscription
• outseta:planUid - The Uid of the subscription plan the account is on
• outseta:addOnUids - An array of add-on Uids associated with the subscription
• outseta:accountClientIdentifier - A custom identifier you may have set for the account

Token Metadata

• exp - Expiration time (Unix timestamp). After this time, the token is no longer valid.
• nbf - "Not before" time (Unix timestamp). The token is not valid before this time.
• iat - "Issued at" time (Unix timestamp). When the token was created.
• iss - Issuer (your Outseta domain)
• aud - Audience (your Outseta domain)

Understanding Person vs Account

When working with the JWT payload, it's important to understand the relationship between people and accounts:

• Person (sub) - An individual user who can log in
• Account (outseta:accountUid) - The billing entity that has a subscription
• Multiple people can belong to the same account (team members)
• The outseta:isPrimary field indicates which person is the primary contact and in charge of billing.

Example: In a company account, you might have 5 team members (people) all belonging to one account. Each person would have their own sub value, but they would all share the same outseta:accountUid, outseta:subscriptionUid, and outseta:planUid.