Admin Portal

Enterprise onboarding usually stalls in the same place: your customer’s IT admin has the identity provider metadata, the DNS zone, and the SIEM token — and none of them can be emailed to you without somebody’s security team objecting.

The Admin Portal removes you from the middle. You mint a signed, expiring link and send it. The admin opens it, configures their own SSO, directory sync, verified domains, or log streams, and never needs an account with you, a password, or an API key.

Mint a link

Requires org:write on the target organization.

POST /v1/organizations/org_01J…/portal_link
Authorization: Bearer sk_live_…

{ "intent": "sso" }

{
  "token": "eyJhbGciOiJFZERTQSIs…",
  "url": "https://acme.oauth.work/u/portal?token=eyJ…",
  "expires_at": 1750000900
}

Send the url. It points at the customer’s own tenant host, not at your console — which is both less confusing for them and necessary, since the session it establishes is host-scoped.

Intents

intent bounds what the link can do. A link minted for SSO cannot be used to add a log stream, even by the same person.

intent	The admin may configure
sso	OIDC or SAML connections, SAML certificate renewal
dsync	SCIM directory sync tokens
domains	Domain verification (DNS TXT)
log_streams	Audit log streaming destinations
both	All of the above (the default)

Anything not passed, or not one of these values, falls back to both. Prefer a narrow intent: send the SSO link when you are setting up SSO, and mint a separate one later if the customer wants log streaming.

Link lifetime and single use

• The link is valid for 15 minutes.
• It can be exchanged once. The first exchange burns it.
• The exchange yields a working session valid for 1 hour.

That combination matters because the token travels in a URL — through mail, through browser history, through whatever proxy logs sit in between. Because it is single-use, a link recovered from any of those places afterwards is already spent. If a customer needs longer than an hour, mint another link.

What the admin sees

Opening the link exchanges the token for a session and returns everything the setup screens need, including the service-provider values the admin has to paste into their identity provider:

{
  "portal_session": "ps_…",
  "expires_in": 3600,
  "org_id": "org_01J…",
  "intent": "sso",
  "acs_url": "https://acme.oauth.work/saml/acs",
  "sp_entity_id": "https://acme.oauth.work",
  "scim_base_url": "https://acme.oauth.work/scim/v2",
  "allows": { "sso": true, "dsync": false, "domains": false, "log_streams": false }
}

From there the flows are the self-serve equivalents of the management API:

• SSO — create an OIDC or SAML connection. For SAML the admin can paste the identity provider’s EntityDescriptor XML or give a URL to fetch it, and the entity id, SSO URL, and certificate are extracted automatically. They can also renew an expiring signing certificate here, which is the single most common reason an established SAML integration breaks.
• Directory sync — mint a SCIM token and get the base URL to paste into their provisioning configuration. See SCIM.
• Domains — add a domain, receive the TXT record, and verify it once DNS has propagated. See verified domains.
• Log streams — point their SIEM at the audit trail. See log streaming.

Auditing

Portal actions land on the same audit trail as everything else, with admin-portal as the actor — so sso_connection_created, scim_token_created, org_domain_verified, saml_cert_renewed, and log_stream_created are all attributable to the portal session rather than to one of your API keys.

When to use it

Use the portal for anything the customer owns: identity provider metadata, DNS records, SIEM tokens. Use the management API for anything you own: provisioning the tenant, minting keys, adding members, registering agents.

The dividing line is who holds the secret. If configuring something correctly requires a credential that belongs to the customer, sending them a portal link is faster than any amount of back and forth — and it means that credential never passes through your support channel.