Skip to content
Dashboard
Theme
Theme

Create a portal setup link

POST /v1/portal/links: Create a portal setup link.

View Markdown

POST /v1/portal/links

Scope
portal_links:write
Auth
Secret key (sk_…)
Since
1.0
  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • Idempotency-Key string

    Honoured for 24 h; a replay returns the original response.

    min length 1 · max length 255

  • profile string

  • organization string Required

  • intents array of string Required

  • return_url string (uri)

  • success_urls object

  • connection string

  • ttl integer

    Seconds, 60 to 300, for a sealed single-use embed link. Leave it out for a setup link, whose lifetime expires_in sets. Not together with expires_in.

    min 60 · max 300

  • expires_in integer

    Seconds the setup link lasts, 300 (5 minutes) to 2592000 (30 days); default 604800 (7 days), the same whether the link is created through the API or in the dashboard. A link an API key creates opens once; one a member creates in the dashboard can be opened again until it ends. Both are revocable; expires_at says when the link ends. Outside the range, or sent with ttl, the request is refused with parameter_invalid (param expires_in).

    min 300 · max 2592000 · default 604800

  • locale string

    A portal language (BCP 47): en, or one of the machine-translated de, es, fr, ja, pt-BR. Optional on a link or invite; any other value answers parameter_invalid (param locale). The set may grow within v1; clients treat an unknown value as English.

Errors share one shape; see the error code catalogue.

curl -X POST \
"https://api.ohauthcat.com/v1/portal/links" \
-H "Authorization: Bearer $OHAUTHCAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organization": "org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"intents": [
"sso"
]
}'
Response 201
{
"id": "plink_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"object": "portal_link",
"url": "https://app.acme.com/callback",
"expires_at": "2026-01-15T09:30:00Z"
}