Connecting Apps with OAuth (Connected Apps)
API keys are for your own code. When a third-party product needs to act in SignStack on a user's behalf — an AI assistant through the MCP server, for example — it connects as a connected app through OAuth 2.1. The user never hands over a key: they sign in to SignStack, choose one organization and one namespace, approve a set of permissions, and the app receives tokens bound to exactly that.
This guide explains what a connection is, what the user sees, what the app receives, and how to build a client if you are integrating a product with SignStack.
What a connection is
A connection (a grant) is one user's consent to one app for one namespace. It carries:
- the organization and namespace the app may reach — and only that namespace; the namespace's mode (
testorlive) comes with it, - the scopes the app holds — what the app asked for, limited to what the user themselves holds in that namespace, plus any optional scopes the user opted into,
- who connected it and when, and when the app last used it.
A user who needs an app in two namespaces connects twice. A namespace Admin can see and revoke every connection in the namespace; everyone else sees their own.
What the user sees
Connecting from the app opens SignStack's consent screen:
- Sign in (if not already signed in).
- Pick the organization and namespace. The namespace's mode is shown so a test connection is never mistaken for a live one.
- Review the permissions. Each requested scope is shown in plain language. A scope the user does not hold in that namespace is shown locked with the role that would grant it — the app will not receive it. Scopes the app marked optional are shown unchecked.
- Allow or deny. On Allow access the browser returns to the app with an authorization code; on Deny it returns with
error=access_denied.
Afterwards the connection is listed in Settings → Integrations, where it can be disconnected at any time.
What the app receives
- An access token — a JWT valid for one hour, sent as
Authorization: Bearer <token>on every call. It is the same kind of token an API key is exchanged for, so every endpoint accepts it. Itsaudnames the resource it was issued for — the SignStack API by default, or the MCP server when the client asked for the MCP server URL asresource(https://mcp.signstack.ai/mcpin production); a token issued for one is refused by the other. - A refresh token — opaque, valid for 90 days of inactivity, and rotated on every use: each refresh returns a new refresh token and retires the old one. Presenting a retired refresh token again revokes the whole connection, because it means a copy has leaked.
On every refresh the granted scopes are re-checked against what the consenting user currently holds. If the user was demoted, the app's access shrinks with them within one token lifetime. Scopes never grow on refresh.
Revoking
A connection ends when:
- the user (or a namespace Admin) disconnects it in Settings → Integrations, or calls
DELETE /v1/orgs/{orgId}/namespaces/{namespaceKey}/connected-apps/{grantId}; - the app revokes one of its tokens at
POST /v1/oauth/revoke(RFC 7009); - a refresh token is reused, or an authorization code is replayed.
Revocation stops refresh immediately and refuses the connection's access tokens on their next request.
Registering a client
A client needs a client_id before it can send anyone to the consent screen. There are three ways to get one.
Pre-registration (verified clients). Ask SignStack to register your client. You receive a client_id (oc_…) and, for a confidential client, a client_secret, against the redirect URIs you provide. Pre-registered clients can request any scope, including privileged ones such as signing links, and are shown without an Unverified notice.
Client ID Metadata Document (self-registration, recommended). Host a JSON document at an HTTPS URL and use that URL as your client_id. SignStack fetches it the first time it sees the client (and again when its cache expires), and accepts it if:
- the document's
client_idis exactly the URL it was fetched from; client_nameis present (at most 100 characters);redirect_urislists one to ten URIs, each HTTPS or a loopbackhttp://localhost,http://127.0.0.1orhttp://[::1]address;- the document offers the
"none"token-endpoint authentication method, astoken_endpoint_auth_methodor amongtoken_endpoint_auth_methods_supported(a document that names no method counts as"none") — metadata-document clients are registered as public clients, whatever else the document prefers; client_uriandlogo_uri, if present, are HTTPS.
The URL must resolve to a public address; a document that redirects, exceeds 64 KiB or takes more than five seconds is refused. This is the mechanism Claude and Claude Code use, and the one the MCP specification recommends. SignStack advertises it with client_id_metadata_document_supported: true.
Dynamic registration (RFC 7591). POST /v1/oauth/register with a JSON body:
{
"client_name": "My assistant",
"redirect_uris": ["https://assistant.example.com/oauth/callback"],
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"]
}
The response carries the issued client_id (oc_…) and the accepted metadata. With token_endpoint_auth_method absent or "none" the client is public and receives no secret. With "client_secret_post" or "client_secret_basic" it is confidential: the response also carries a client_secret (with client_secret_expires_at: 0). That secret is shown only once, and the client must present it at the token endpoint. A secret changes nothing else; the client still uses PKCE and is still self-registered. The redirect URI rules are the same as above, and metadata SignStack does not know is ignored. Registration is rate-limited per address, and a registered client that never completes a connection is removed after thirty days. The endpoint is advertised as registration_endpoint in the server metadata.
Self-registered clients — both kinds — are shown as Unverified on the consent screen and in Settings, with the hostname the flow returns to and a warning when every redirect URI is a loopback address. They may request only the self-service scope set: workflow:read, workflow:create, workflow:update, resource:read, resource:create, resource:update, scenario:read, scenario:create, scenario:update, shareable-link:read, shareable-link:create and shareable-link:update. Anything else fails with invalid_scope. A grant keeps the scopes it was approved with: a connection made while the set was smaller gains the newer ones only when the user connects again.
Loopback redirects. A redirect URI registered as http://localhost/callback or http://127.0.0.1/callback matches a request with any port (http://127.0.0.1:54321/callback), so native clients that bind an ephemeral port per session work; scheme, host, path and query must still match. All other redirect URIs must match exactly.
Building a client
Once you have a client_id:
- Discover the server.
GET /.well-known/oauth-protected-resourcenames the authorization server (GET /.well-known/oauth-protected-resource/mcpdoes the same for the MCP server);GET /.well-known/oauth-authorization-serverlists the endpoints, supported grant types (authorization_code,refresh_token), PKCE methods (S256), registration options and scopes. - Send the user to authorize.
GET /v1/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&state=…&code_challenge=…&code_challenge_method=S256. PKCE andstateare required for every client. Request only the scopes you need. A pre-registered client can have the scopes it can live without marked optional, so the user is not forced to grant them; a self-registered client has no optional scopes. Addresource=<MCP server URL>(https://mcp.signstack.ai/mcpin production) to obtain a token for the MCP server instead of the REST API. - Exchange the code.
POST /v1/oauth/tokenwithgrant_type=authorization_code,code,redirect_uri,code_verifier, and your client credentials. Codes are single-use and expire after ten minutes. - Label the connection.
GET /v1/auth/whoamireturns the organization name, namespace name and mode the token is bound to — show them to the user so they can tell connections apart. - Refresh before expiry with
grant_type=refresh_token, storing the new refresh token every time. - Handle revocation. A
401on an otherwise valid token means the connection was revoked; ask the user to reconnect.
The token, revocation and registration endpoints answer errors in the standard OAuth shape ({"error": "invalid_grant", "error_description": "…"}), not in the API's usual error envelope.
When to use which
| You are… | Use |
|---|---|
| Writing your own backend against your own namespace | An API key |
| Embedding SignStack components in your product | Embed session tokens |
| A third-party product acting for many SignStack users | A connected app (this guide) |
| Letting an AI assistant work in a namespace | Connect it to the MCP server — it is a connected app |
