{"info":{"_postman_id":"bd168430-ecf9-43c8-af88-c557e66e8e88","name":"OneHQ — SSO API-Key Login","description":"\n

This collection demonstrates organization-level Single Sign-On for external clients. It enables an external system (for example, a WordPress site) to sign a user into a OneHQ application without prompting for a password or a second factor. A single GraphQL mutation, authenticated with your organization's API key, returns a one-time URL; directing the user's browser to that URL establishes their session.

1. Obtain an API key

API keys are created and managed in the OneHQ administration interface, not in Postman:

Navigate to Organization → Edit → Security.
Under SSO API Keys, select + to add a key.
Provide a Name, the target Application (the application the user will be signed in to), a Permission, and an Alert email. The Permission controls how an unknown email is handled:
- auth_only — only existing users may sign in; an unknown email is rejected (user_not_found), no account is created.
- auth_or_create — an unknown email automatically provisions a new account (on the bound application, with the key's role) and signs in.
\n
Select Save. The client secret (sk_live_...) is displayed only once. Record it immediately, as it cannot be retrieved afterward. This secret is the credential you provide to the collection (see step 2).

2. Configure the collection variables

In the collection's Variables tab, set the following:

baseUrl: the OneHQ SSO endpoint (https://sso.onehq.com).
apiKey: the client_secret (sk_live_...) obtained in step 1.
email: the user to authenticate. For auth_only keys, the user must belong to the key's organization.

3. Execute the flow

Send the ssoLogin request. It returns a one-time redirectUrl, valid for approximately five minutes and usable once.
Open the redirectUrl in a browser. The user is signed in without a password or second factor.

Security

The API key must be provided in the Authorization: Bearer <client_secret> header, which is already configured on the request. It must never be placed in the request body, where it could be recorded in server logs.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"OneHQ — SSO API-Key Login","slug":"onehq-sso-api-key-login"}],"owner":"13507213","collectionId":"bd168430-ecf9-43c8-af88-c557e66e8e88","publishedId":"2sBXwwn87v","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-06-23T17:49:33.000Z"},"item":[{"name":"ssoLogin — get one-time redirect URL","event":[{"listen":"test","script":{"type":"text/javascript","exec":["const res = pm.response.json();","const payload = res && res.data && res.data.ssoLogin;","","pm.test('HTTP 200', () => pm.response.to.have.status(200));","pm.test('returns an ssoLogin payload', () => pm.expect(payload, JSON.stringify(res)).to.be.an('object'));","","if (payload && payload.redirectUrl) {"," pm.collectionVariables.set('redirectUrl', payload.redirectUrl);"," const st = payload.redirectUrl.match(/st=([^&]+)/);"," if (st) pm.collectionVariables.set('st', decodeURIComponent(st[1]));"," const ticket = payload.redirectUrl.match(/ticket=([^&]+)/);"," if (ticket) pm.collectionVariables.set('ticket', decodeURIComponent(ticket[1]));"," pm.test('expiresIn is 300', () => pm.expect(payload.expiresIn).to.eql(300));","} else {"," console.log('ssoLogin error:', payload && payload.error, payload && payload.message);","}"],"id":"5822a84a-1351-4dc8-a9a1-263de696d913"}}],"id":"336f8d6f-b30a-4690-8305-f14d3f57d373","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer sk_live_REPLACE_ME"}],"body":{"mode":"raw","raw":"{\n \"operationName\": \"SsoLogin\",\n \"query\": \"mutation SsoLogin($email: String!) { ssoLogin(email: $email) { redirectUrl expiresIn error statusCode message } }\",\n \"variables\": {\n \"email\": \"user@your-org.com\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://sso.onehq.com/gql","description":"

Validates the API key, resolves (or creates) the user, and returns a single-use redirectUrl.

Authentication

The API key is sent in the Authorization: Bearer sk_live_REPLACE_ME header — never in the body. operationName must be SsoLogin (this operation is allowed pre-authentication based on the operationName).

Permission modes (configured per key)

auth_only — only existing users may sign in; an unknown email returns user_not_found (404), no account is created.
auth_or_create — an unknown email provisions a new account (on the key's bound application, with the key's role) and signs in.

Redirect URL form

Determined by the application the key is bound to:

HQAdmin → <host>/sso/consume?st=<JWT> (self-consumed)
Any other application → <application-url>/users/service?ticket=<ST> (the user lands in that application)

To chain the user onward after sign-in, append &redirect_to=<path> to the returned URL.

Response (`data.ssoLogin`)

This is a GraphQL mutation: a well-formed request returns HTTP 200. The outcome is carried in the body under data.ssoLogin. The statusCode field is an application-level code in the payload — NOT the HTTP status.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Notes
`redirectUrl`	String	one-time URL on success; null on error
`expiresIn`	Int	seconds to expiry (300) on success; null on error
`error`	String	error code; null on success
`statusCode`	Int	application status for certain errors; null otherwise
`message`	String	human-readable description

Error codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`error`	`statusCode`	Condition
`invalid_api_key`	null	missing, malformed, or revoked/rotated key
`user_not_found`	404	`auth_only` key and the email has no account in the organization
`no_app_access`	403	the user cannot access the key's bound application
`login_not_allowed`	403	the user is locked, disabled, or not permitted to sign in
`rate_limited`	429	more than 60 requests per minute for the key
`sso_login_error`	null	unexpected server-side error

A revoked or rotated key returns invalid_api_key on the next call (observable on the mint call, so revocation can be detected proactively).

Alerts

If the key has an alert email configured, an alert is sent when the key exceeds its rate limit (more than 60 requests per minute).

\n","urlObject":{"path":["gql"],"host":["https://sso.onehq.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"336f8d6f-b30a-4690-8305-f14d3f57d373"},{"name":"Consume ticket (browser only)","id":"8f74f762-c3ca-4009-a3b0-b7293734b6da","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://sso.onehq.com/sso/consume?st=","description":"

The final step is meant for a real BROWSER, not Postman: opening the redirectUrl verifies the single-use ticket, establishes the session cookie and redirects the user into the UI.

This request is here for reference. Calling it from Postman will consume the ticket (single-use) and set a cookie, but won't render the app. Use it only to inspect the 302 redirect.

HQAdmin path only — other apps consume their own ?ticket= via CAS.

\n","urlObject":{"path":["sso","consume"],"host":["https://sso.onehq.com"],"query":[{"key":"st","value":""}],"variable":[]}},"response":[],"_postman_id":"8f74f762-c3ca-4009-a3b0-b7293734b6da"}],"variable":[{"key":"baseUrl","value":"https://sso.onehq.com","description":"The OneHQ SSO endpoint. All requests in this collection are sent to this host (for example, POST https://sso.onehq.com/gql)."},{"key":"apiKey","value":"sk_live_REPLACE_ME","description":"The organization's API key client secret (sk_live_...). It is created in the OneHQ administration interface: Organization → Edit → Security → SSO API Keys → add a key → copy the secret shown once. It is provided in the Authorization: Bearer header, never in the request body."},{"key":"email","value":"user@your-org.com","description":"The email of the user to log in. Must exist in the key's organization for auth_only keys."},{"key":"redirectUrl","value":"","description":"Captured from the last ssoLogin response."},{"key":"st","value":"","description":"Captured service-ticket JWT (HQAdmin self-consume path)."},{"key":"ticket","value":"","description":"Captured CAS service ticket (other apps)."}]}

OneHQ — SSO API-Key Login