How to Get an Okta API Token

To get an Okta API token, sign in to your Okta Admin Console as an admin, go to Security → API → Tokens, click Create Token, name it, click the button to generate it, and copy the value immediately — it's only shown once. Tokens are sent in the Authorization header using the SSWS scheme: Authorization: SSWS <token>.

One thing to know before you start: Okta explicitly recommends using OAuth 2.0 access tokens over SSWS API tokens for new production integrations, because OAuth tokens are short-lived and scope-limited. If you're building something long-lived or distributing an app to other Okta orgs, jump to the OAuth section below. API tokens are faster to test with and still widely used for internal tooling and scripts.

Prerequisites

• An Okta admin account — at minimum the Read-Only Admin role to generate a token, though most management operations require Super Admin or the specific admin role covering the resources you're working with (Okta Docs, Administrators).
• A decision: if you're writing a tool that connects to other organisations' Okta orgs, you need OAuth 2.0 (not a personal API token). Tokens are single-org credentials.
• Optionally: the network zones your integration will call from, if you want to restrict the token to specific IP ranges.

Step-by-step: creating an Okta API token

1. Sign in to your Okta org as an administrator at https://{yourOktaDomain}/admin.
2. In the Admin Console, go to Security → API.
3. Click the Tokens tab.
4. Click Create Token.
5. Enter a descriptive name for the token — something that identifies the service that will use it (e.g., datawarehouse-users-read), not a person's name.
6. Optionally, configure the network zone restrictions: specify the IP addresses or ranges that are allowed to use this token. Requests from any other IP will be rejected.
7. Click Create Token.
8. Copy the token value now. The full token is only displayed once at creation. If you lose it, you must delete the token and create a new one (Okta Docs, Create an API token).

Where the credential goes

Send the token in every request's Authorization header using the SSWS scheme:

Authorization: SSWS <your-api-token>

Note that the scheme is SSWS, not Bearer — this is Okta's proprietary authentication scheme and one of the most common sources of 401 errors (Okta Docs, Core Okta API — Authentication).

The base URL for all management API calls is https://{yourOktaDomain}/api/v1/, where {yourOktaDomain} is your org's subdomain (e.g., https://yourcompany.okta.com/api/v1/).

Token behaviour to know:

• Lifetime: tokens expire after 30 days of inactivity. The clock resets on every successful API call, so a token used regularly stays alive. A token that hasn't been used in 30 days is silently expired.
• Privilege level: the token inherits the full privilege level of the admin account that created it. If that admin's role changes, the token's effective permissions change silently to match — this is a good reason to use a dedicated service account for each token.
• Revocation: if the admin account that created the token is deactivated in Okta, the token is deprovisioned immediately (Okta Docs, Create an API token).
• Rate limit: each new token is set to 50% of each API endpoint's maximum rate limit. You can adjust this from the Token Rate Limits section in Admin → Security → API → Tokens.

Minimal working example

This lists the first two active users in your org — a good smoke test that the token and network access are working.

curl:

curl "https://${OKTA_DOMAIN}/api/v1/users?limit=2&filter=status+eq+%22ACTIVE%22" \
  -H "Authorization: SSWS ${OKTA_API_TOKEN}" \
  -H "Accept: application/json"

Node.js

const res = await fetch(
  `https://${process.env.OKTA_DOMAIN}/api/v1/users?limit=2&filter=status+eq+"ACTIVE"`,
  {
    headers: {
      Authorization: `SSWS ${process.env.OKTA_API_TOKEN}`,
      Accept: "application/json",
    },
  }
);

console.log(await res.json());

Store OKTA_DOMAIN (e.g., yourcompany.okta.com) and OKTA_API_TOKEN as environment variables — never hard-code them in source control.

OAuth 2.0 - the recommended alternative

For new production integrations, Okta recommends OAuth 2.0 scoped access tokens over SSWS tokens. They're shorter-lived (1 hour for OAuth for Okta flows), limited to specific scopes, and can be rotated programmatically. To set this up:

1. In Admin Console, go to Applications → Applications → Create App Integration.
2. Choose OIDC – OpenID Connect as the sign-in method and Web Application as the app type.
3. After saving, go to the Okta API Scopes tab and grant the scopes your integration needs (e.g., okta.users.read, okta.groups.manage). Only Super Admin can grant scopes.
4. Request an access token from your org's authorization server:https://{yourOktaDomain}/oauth2/v1/authorize
5. Use the resulting token as Authorization: Bearer <access-token>.

Gotcha: Okta OAuth scopes follow the okta.<resource>.<operation> pattern — for example, okta.users.read to list users, okta.users.manage to create or modify them. "Silent downscoping" applies: if you request a scope that exists in the app's grant collection but your user account lacks the underlying permission, the token is issued with that scope but any API call using it will fail with a 403. Always test API calls, not just token issuance (Okta Docs, Implement OAuth for Okta).

See the Okta API overview for a summary of which approach to use for each scenario.

Common errors and fixes

Why am I getting a 401 Unauthorized?

‍Almost always one of three things: (1) the Authorization header is using Bearer instead of SSWS for an API token — change it to Authorization: SSWS <token>; (2) the token has expired due to 30 days of inactivity — generate a new one; or (3) the token was created by an admin account that has since been deactivated — it's been deprovisioned, so a new token from an active admin account is needed.

Why am I getting a 403 Forbidden?

‍The admin account that created the token doesn't have the role required for that operation. For example, the Users API requires at least the User Administrator role for writes. Check the privilege level of the service account used to create the token, and if necessary recreate the token from an account with sufficient permissions.

Why am I getting a 429 Too Many Requests?

‍You've hit either the per-token rate limit (50% of the endpoint's maximum by default) or an org-wide bucket limit. Check the response headers X-Rate-Limit-Remaining and X-Rate-Limit-Reset (Unix timestamp of when the window resets). Either back off and retry after the reset time, or go to Admin → Security → API → Tokens and increase the token's rate limit percentage. For sustained high-volume workloads, consider DynamicScale or distributing requests across multiple tokens (Okta Docs, Rate limits).

The faster way

Generating and rotating Okta API tokens, keeping the privilege level in sync with a service account, watching the 30-day inactivity expiry, and handling Okta's bucket-based rate limits across Users, Groups, and Apps all adds up — and that's before you add a second HRIS or directory tool. Knit's unified HRIS API handles Okta's auth and rate-limit backoff for you and normalises users, groups, and directory data across connectors like BambooHR and Workday behind one schema. See the Okta API overview for what's available, or book a demo to see it live. You can also sign up free and connect a sandbox Okta org.

FAQ

What is the difference between an Okta API token and an OAuth 2.0 access token?

‍An Okta API token uses the SSWS authentication scheme, inherits the full privilege level of the admin who created it, and is valid for 30 days from last use. An OAuth 2.0 access token is scope-limited, short-lived (typically 1 hour), and can be generated programmatically. Okta recommends OAuth 2.0 for new production integrations because it limits the blast radius of a compromised credential.

How do I use an Okta API token in API calls?

‍Include it in the Authorization header using Okta's SSWS scheme — Authorization: SSWS <your-token> — on every request to https://{yourOktaDomain}/api/v1/. The scheme name is SSWS, not Bearer.

Do Okta API tokens expire?

‍Yes. Tokens expire after 30 days of inactivity. The expiry is rolling — each successful API call resets the 30-day clock. If your integration stops calling the API for 30 days straight, the token silently expires and any subsequent call returns a 401.

Can I restrict which IPs can use my Okta API token?

‍Yes. When creating a token, or by editing an existing one, you can specify network zones (sets of IP addresses or CIDRs) that are allowed to use the token. Requests from outside those zones are rejected even with a valid token.

What happens if the admin who created the token leaves the company?

‍If their Okta account is deactivated, the token is deprovisioned immediately. This is why Okta recommends creating tokens under a dedicated service account with the minimum required admin role, rather than under a personal admin account.

Sources:

• Create an API token — Okta Developer Docs
• Core Okta API — Okta Developer Docs
• Implement OAuth for Okta — Okta Developer Docs
• Rate limits — Okta Developer Docs
• Manage Okta API tokens — Okta Help Center

‍