Start a sign-in

The authorization endpoint. It checks the app and its redirect URI, keeps the request 30 minutes and shows the consent page, where the person's device key signs.

GET/oidc/authorize

Access: Public access
Client: Local or server client

Parameters#

Name	Location	Meaning
`response_type`Required	Query	code.
`client_id`Required	Query	The app's client_id.
`redirect_uri`Required	Query	Exactly one the app registered (a loopback URI with any port).
`scope`Required	Query	openid, and any of profile veil veil:accounts veil:orgs veil:keys.
`code_challenge`Required	Query	BASE64URL(SHA-256(code_verifier)), 43 characters.
`code_challenge_method`Required	Query	S256.
`state`	Query	Up to 1024 characters; returned as is, and its SHA-256 is in the signed consent.
`nonce`	Query	Up to 512 characters; in the signed consent and in the ID token.
`prompt`	Query	none, or any of login consent select_account.
`ui_locales`	Query	it shows the page in Italian.

Request examples#

cURL

curl -fsS 'https://veil.rip/oidc/authorize?response_type=code&client_id=veil_app_0123456789abcdef0123456789abcdef&redirect_uri=https%3A%2F%2Fapp.example.org%2Fcallback&scope=openid%20profile%20veil&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256'

Response#

HTTP 200text/html

The consent page (HTML). After the signature the browser goes to redirect_uri with code, state and iss.

Response headers#

Header	Value	Meaning
`Cache-Control`	`no-store`	The page carries a request id.

What to verify#

At the redirect URI check state, then iss equals https://veil.rip, before you exchange the code.

Usage notes#

An unknown app or a redirect URI it did not register is refused on the page and never redirected to. Every other mistake goes back to the app as error= with state and iss.
Errors back at the app: invalid_request, invalid_scope, unsupported_response_type, request_not_supported, request_uri_not_supported, access_denied, login_required, consent_required.

Errors#

The OAuth callback renders an HTML return page, including when it fails. The codes below describe the failure shown on that page. Response and error guide

HTTP Code Meaning and next step

400

HTTP	Code	Meaning and next step
400	`invalid_request`	OAuth error: a parameter is missing, given twice or malformed, or the body is not a form. Read `error_description`, fix the request and send it again.

invalid_request

OAuth error: a parameter is missing, given twice or malformed, or the body is not a form.

Read error_description, fix the request and send it again.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON