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/authorize

Approve or decline Extension

Records the decision. Every authorization parameter is re-validated from scratch rather than trusted from the session, and workspace_id names which workspace the grant is scoped to — a person in several workspaces authorizes one of them, not all. A decline is not an error: it redirects to the client with error=access_denied.

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/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 /oauth/authorizations

List connected applications Extension

What this person has approved: which application, which workspace, which scopes, and when it was last used. Not reachable with an OAuth bearer token — no scope grants it, and a credential must not be able to enumerate or revoke credentials.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Responses

Example request

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

DELETE /oauth/authorizations/{id}

Disconnect an application Extension

Revokes the grant and every token under it in one transaction. The bearer guard caches nothing, so it takes effect on the next request; the sixty seconds in the metadata document is a ceiling on a resource server's own introspection cache, not slack here.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X DELETE https://api.signclad.com/api/v1/oauth/authorizations/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /oauth/clients

List server-to-server clients Extension

Confidential clients for the client credentials grant. Owner and admin only, and never reachable with an OAuth token: a credential must not be able to mint credentials.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Responses

Example request

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

POST /oauth/clients

Create a server-to-server client Extension

Mints a confidential client and returns its secret once. offline_access is dropped if asked for — a client credentials token has nobody to refresh on behalf of. Omitting scopes gives documents:read, documents:write, and templates:read.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

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

DELETE /oauth/clients/{id}

Delete a server-to-server client Extension

Revokes the client and its tokens.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X DELETE https://api.signclad.com/api/v1/oauth/clients/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"