OAuth API

GET /.well-known/oauth-authorization-server

Authorization server metadata Extension

RFC 8414 discovery. Everything a client needs to talk to the authorization server without hard-coding a URL. Cached for five minutes. The same document is served from any path suffix (/.well-known/oauth-authorization-server/anything), because clients differ on where they look.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Responses

Example request

curl -X GET https://api.signclad.com/.well-known/oauth-authorization-server \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /.well-known/oauth-protected-resource

Protected resource metadata Extension

RFC 9728 discovery: which authorization server protects this API, which scopes it understands, and how long a resource server may cache an introspection result.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Responses

Example request

curl -X GET https://api.signclad.com/.well-known/oauth-protected-resource \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /oauth/authorize

Show the consent screen Extension

The authorization endpoint. PKCE is mandatory: code_challenge with code_challenge_method=S256, no exceptions and no default. response_type must be code; there is no implicit grant. The screen is skipped when there is nothing to decide. A grant that already covers this client, this audience, and every requested scope is honoured silently and the browser goes straight back with a code — showing a consent screen for something already approved only teaches people to click through consent screens. Three things force it anyway: prompt=consent, a request for a scope the existing grant does not carry, and a grant whose workspace the person has since left. Otherwise, three possible answers. No session redirects to the login page with a redirect back here. A browser gets the consent page as HTML. Accept: application/json gets the same information as JSON, for a SPA rendering its own consent screen. Failures split by whether the redirect URI can be trusted yet. An unknown client, or a redirect_uri that does not exactly match a registered one, is answered here — never redirected, because redirecting would make this an open redirector. Everything after that (bad scope, bad PKCE, bad resource) redirects to the client with error, error_description, the state if there was one, and always iss.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/oauth/authorize \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /oauth/token

Exchange a grant for a token Extension

Three grants: authorization_code, refresh_token, and client_credentials. Confidential clients authenticate with HTTP Basic or with client_id and client_secret in the body; public clients send client_id alone and are refused if they present a secret. Refresh tokens rotate and detect reuse. Using one twice revokes the whole family and forces a fresh authorization — the reply says so. A refresh may narrow scope, never widen it, and can never change the token's audience. refresh_token is present only when offline_access was granted, and never on client_credentials. nonce comes back only when the code carried one.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Request body

application/x-www-form-urlencoded

Responses

Example request

curl -X POST https://api.signclad.com/oauth/token \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "access_token": "sca_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:read documents:write offline_access",
  "refresh_token": "scr_1a2b3c4d5e6f708192a3b4c5d6e7f809"
}

POST /oauth/register

Register a client dynamically Extension

RFC 7591 dynamic registration, unauthenticated, so an assistant can connect without anybody pasting a client id. It issues public clients only: token_endpoint_auth_method must be none, and a confidential client for server-to-server work is created in the app instead. Redirect URIs must be HTTPS, a loopback address, or a reverse-domain private-use scheme. The response carries a registration_access_token and registration_client_uri — the only time the token is shown.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/oauth/register \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /oauth/register/{client_id}

Read a dynamic registration Extension

RFC 7592. Authenticated with the registration_access_token as a bearer token. Returns the same document as the registration minus the token and the management URI. A client that was not dynamically registered is a 404.

Base URL

https://api.signclad.com

Authentication

Registration access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/oauth/register/{client_id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /oauth/revoke

Revoke a token Extension

RFC 7009. Answers 200 with a JSON null body whether the token existed, was already revoked, belonged to another client, or was never ours — a revocation endpoint that distinguished those would be a token oracle. token_type_hint is accepted and ignored.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Request body

application/x-www-form-urlencoded

Responses

Example request

curl -X POST https://api.signclad.com/oauth/revoke \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /.well-known/oauth-authorization-server/{tail}

Authorization server metadata, resource-suffixed

The same document as /.well-known/oauth-authorization-server, served at the path-suffixed form RFC 8414 §3.1 describes for an issuer with a path component. Clients differ on which of the two they try first, so Signclad answers both identically rather than making the choice matter.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/.well-known/oauth-authorization-server/{tail} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /.well-known/oauth-protected-resource/{tail}

Protected resource metadata, resource-suffixed

The same document as /.well-known/oauth-protected-resource, served at the path-suffixed form RFC 9728 describes. The WWW-Authenticate header on a 401 points at the bare path; both answer identically.

Base URL

https://api.signclad.com

Authentication

None — this operation is public

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/.well-known/oauth-protected-resource/{tail} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"