Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt

Use this file to discover all available pages before exploring further.

Toktra supports enterprise SSO via SAML 2.0 and automated user provisioning via SCIM 2.0. This guide walks through configuring your identity provider, testing the connection, and understanding what gets synced.

​
Supported identity providers

Use the SAML 2.0 app integration in the Okta Admin Console. Okta also supports SCIM provisioning via the Toktra SCIM endpoint.

​
SAML 2.0 SSO setup

​
Step 1: Get your SP metadata

Toktra acts as the SAML Service Provider (SP). Retrieve the SP metadata XML to configure your IdP: 
GET /v1/sso/metadata?org_id=<your-org-id>
The response is standard SAML 2.0 SP metadata XML. You can upload this file directly in Okta, Azure AD, or Google Workspace instead of manually entering each field. Key SP endpoints:
EndpointURL
SP Metadata URLhttps://api.toktra.io/v1/sso/metadata?org_id=<org_id>
ACS (Assertion Consumer Service) URLhttps://api.toktra.io/v1/sso/acs?org_id=<org_id>
SP-initiated loginhttps://api.toktra.io/v1/sso/login?org_id=<org_id>
Single Logout (SLO)https://api.toktra.io/v1/sso/logout?org_id=<org_id>

​
Step 2: Configure your IdP

1

Create a SAML app in your IdP

In Okta: go to Applications → Create App Integration → SAML 2.0. In Azure AD: go to Enterprise Applications → New application → Create your own application → Integrate any other application. In Google Workspace: go to Apps → Web and mobile apps → Add app → Add custom SAML app.
2

Upload SP metadata or enter values manually

If your IdP supports metadata upload, paste the URL from the step above or upload the downloaded XML.If you must enter values manually, use:
  • ACS URL: https://api.toktra.io/v1/sso/acs?org_id=<org_id>
  • Entity ID / Audience: https://api.toktra.io (or the value in the SP metadata entityID attribute)
  • Name ID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
3

Map attributes

Toktra requires the following attributes in the SAML assertion:
AttributeIdP claimNotes
emailUser emailRequired. Used as the user’s primary identifier.
firstNameGiven nameOptional but recommended.
lastNameFamily nameOptional but recommended.
departmentDepartmentOptional. Used for budget scoping.
4

Save and download IdP metadata

Save the app in your IdP and download the IdP metadata XML (or copy the metadata URL).

​
Step 3: Upload IdP metadata to Toktra

Call POST /v1/sso/config with the IdP metadata: 
{
  "provider": "okta",
  "idp_metadata_xml": "<base64-encoded IdP metadata XML>",
  "enabled": true
}
Alternatively, provide the IdP metadata URL and Toktra will fetch it: 
{
  "provider": "azure_ad",
  "idp_metadata_url": "https://login.microsoftonline.com/<tenant>/federationmetadata/2007-06/federationmetadata.xml",
  "enabled": true
}

​
Step 4: Test the SP-initiated login flow

1

Open the login URL in a browser

Visit https://api.toktra.io/v1/sso/login?org_id=<org_id>&relay_state=/. The response contains a redirect_url — open it to be redirected to your IdP’s login page.
2

Authenticate with your IdP credentials

Complete the IdP login. The IdP posts a SAMLResponse to the Toktra ACS endpoint.
3

Verify the callback

On success, the ACS endpoint returns a session token and your relay_state destination. The user is provisioned in Toktra if they do not already exist.
SP-initiated login is the recommended flow. IdP-initiated login (where the user clicks a tile in the IdP portal) is also supported but the relay_state will default to /.

​
SCIM 2.0 provisioning

SCIM automates user and group lifecycle management: when you add, update, or deactivate a user in your IdP, the change is reflected in Toktra automatically. Toktra’s SCIM 2.0 endpoint is fully RFC 7643/7644 compliant and supports the following operations:
ResourceSupported operations
UsersCreate, Read, Update (PUT/PATCH), Delete
GroupsCreate, Read

​
Step 1: Get a SCIM Bearer token

Generate a SCIM Bearer token from the Toktra dashboard:
  1. Go to Settings → SSO / SCIM (SSOConfigPage at /settings/sso).
  2. Click Generate SCIM Token.
  3. Copy the token — it will not be shown again.
Treat the SCIM Bearer token like a password. Anyone with this token can provision and deprovision users in your Toktra organization.

​
Step 2: Configure SCIM in your IdP

In the Okta app you created for SAML, go to Provisioning → Configure API Integration:
  • Base URL: https://api.toktra.io/v1/scim/v2
  • API Token: paste the Bearer token from step 1
  • Click Test API Credentials to verify the connection.
Under Provisioning To App, enable:
  • Create Users
  • Update User Attributes
  • Deactivate Users

​
What SCIM syncs

WhatHow
User creationWhen you assign the Toktra app to a user in your IdP, SCIM creates the user in Toktra.
User updatesProfile changes (name, email, department) in the IdP are synced to Toktra.
User deactivationDeactivating a user in the IdP sets active: false in Toktra. Combined with the Okta user.lifecycle.deactivate webhook, this also triggers the lockout pipeline.
Groups / departmentsSCIM Groups map to Toktra departments, enabling department-level budget enforcement to work automatically as your org chart changes.

​
Step 3: Test the connection

After saving the SCIM configuration in your IdP, trigger a test provisioning event:
  1. Assign a test user to the Toktra app in your IdP.
  2. Verify the user appears in Toktra under Users.
  3. Update the test user’s display name in the IdP and confirm the change syncs within the IdP’s provisioning interval (typically 40 minutes for Okta; near-real-time for Azure AD with on-demand provisioning).
Use the SCIM discovery endpoints to validate your configuration:
  • GET /v1/scim/v2/ServiceProviderConfig — lists supported SCIM features
  • GET /v1/scim/v2/ResourceTypes — lists supported resource types (User, Group)
  • GET /v1/scim/v2/Schemas — lists the SCIM schemas with attribute definitions

​
Rotating credentials

To rotate the SCIM Bearer token, generate a new one from Settings → SSO / SCIM and update the token in your IdP immediately. The old token is invalidated as soon as the new one is generated. To rotate the SAML signing certificate, update the SP certificate in both Toktra (SAML_CERT_PATH / SAML_KEY_PATH) and the IdP app configuration. SAML certificate rotation requires a brief maintenance window to keep both sides in sync.