What kind of authentication does DocJacket's MCP server use?

OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). No static API keys, no shared secrets. Every assistant registers itself, every user grants consent individually, every token is bound to one user and one assistant.

How long does an OAuth access token last?

Access tokens are valid for one hour. Refresh tokens last 30 days and rotate on every exchange — using one invalidates the prior one immediately to limit replay damage.

How do I revoke an assistant's access?

Go to DocJacket → Settings → AI Access, find the assistant in the connected-clients list, and click Revoke. The next request from that client returns 401 Unauthorized; the user will have to re-consent if they want to reconnect.

What are scopes, and why does the consent screen ask about read, draft, and actions?

Scopes are coarse permission buckets. Read covers everything in AI Access v0.9 — searching and viewing data. Draft (v1.0) lets an assistant prepare emails or task suggestions for your approval. Actions (v1.0+) covers sending and modifying. Today only read is enforced; draft and actions appear on the consent screen so you can pre-authorize them for v1.0.

How the OAuth flow works

DocJacket's MCP server is OAuth 2.1 + PKCE + Dynamic Client Registration (RFC 7591). If you've connected an assistant by pasting a URL, what you saw was the discovery / consent dance below — six HTTP requests, ~1 second end-to-end, no keys to manage.

This page is for the curious and for the security-conscious. You don't need to read it to use AI Access — the consent screen is the only step you ever interact with.

See it in action

The 30-second walkthrough above is the entire flow: paste URL → consent screen → Allow → tools loaded. Everything below explains what happens under the hood.

The flow at a glance

Discovery        → assistant fetches DocJacket's well-known metadata
Registration     → assistant creates its own client_id (DCR)
Authorize        → assistant redirects you to DocJacket
Consent          → you see what's being asked, click Allow
Token exchange   → assistant trades the auth code for an access token
Tool calls       → assistant sends MCP requests with the bearer

Each step in detail:

1. Discovery

When you paste https://mcp.docjacket.com/mcp into your assistant, the first thing it does is fetch two well-known metadata documents:

Protected resource metadata (https://mcp.docjacket.com/.well-known/oauth-protected-resource) tells the assistant where to find the authorization server.
Authorization server metadata (https://app.docjacket.com/.well-known/oauth-authorization-server) tells the assistant which endpoints to use for registration, authorization, and token exchange.

This is RFC 9728 + RFC 8414 — the standard auth-server discovery pattern. No proprietary configuration files.

2. Dynamic Client Registration (RFC 7591)

The assistant POSTs to https://app.docjacket.com/oauth/register with its name, redirect URIs, and what it wants to do. DocJacket creates a fresh client_id (prefixed dyn_) and returns it.

This is the magic that makes paste-URL-and-go work: the assistant registers itself the first time you connect. There's no DocJacket admin console where you create API credentials and copy-paste them.

Every assistant gets its own client_id — your Claude.ai connector and your Codex CLI have different ones.

3. Authorize

The assistant redirects you to:

https://app.docjacket.com/oauth/authorize
  ?response_type=code
  &client_id=dyn_...
  &redirect_uri=https://claude.ai/api/mcp/auth_callback
  &code_challenge=...                ← PKCE
  &code_challenge_method=S256
  &state=...
  &scope=read+draft+actions
  &resource=https://mcp.docjacket.com/mcp

If you're not already logged into DocJacket in that browser session, you'll be sent to the login page first and bounced back here after.

You see DocJacket's consent screen:

Connect [Claude] to DocJacket?

This will let the app act on data in your organization.

It will be able to:

read — Read your transactions, tasks, key dates, and contacts.

draft — Prepare emails and task suggestions for your approval. (Nothing sends without your review.)

actions — Send communications and make changes on your behalf. (Per-action confirmation still applies.)

Clicking Allow redirects you back to the assistant with a one-time authorization code.

5. Token exchange

The assistant POSTs the auth code to https://app.docjacket.com/oauth/token along with the PKCE verifier (proving it's the same client that started the flow). DocJacket returns:

access_token — a signed JWT, valid 1 hour, bound to your user, your org, the client, and the resource indicator
refresh_token — opaque token (prefixed mcp_rt_), valid 30 days, single-use (rotates on every exchange)

6. Tool calls

The assistant now POSTs to https://mcp.docjacket.com/mcp with Authorization: Bearer <access_token> and a JSON-RPC body. DocJacket validates the JWT (issuer, audience, signature, expiry) and runs the tool.

If the token is missing or invalid, DocJacket returns HTTP 401 with a WWW-Authenticate: Bearer ... resource_metadata=... header so the assistant can re-discover and re-authenticate.

Scopes

DocJacket exposes three scopes:

Scope	What it covers	Status
`read`	Search transactions, get details, list deadlines, contingencies, missing docs, contacts	Live in v0.9
`draft`	Prepare emails and task suggestions for your approval. Nothing sends.	v1.0
`actions`	Send communications and make changes on your behalf with per-action confirmation	v1.0+

Today the consent screen asks for all three so you can pre-authorize, but only read actually does anything — the others are reserved for the next release.

Refresh + rotation

When the access token expires (1h), the assistant exchanges the refresh token for a new pair. The old refresh token is invalidated immediately — even one millisecond after exchange. This is single-use refresh per OAuth 2.1.

If your assistant misbehaves and tries to reuse a refresh token (e.g., concurrent processes), DocJacket revokes the entire refresh family. The assistant will fall back to re-consent.

Revocation

DocJacket → Settings → AI Access → Connected Clients. Click Revoke on any client.

What happens:

The token row's revoked_at is set in our database immediately.
The next tool call returns HTTP 401 with the same WWW-Authenticate challenge as an unauthenticated request.
The assistant either falls back to re-consent (if you want to reconnect) or fails gracefully (if you don't).

There's no propagation delay — revocation is enforced on the next request.

Resource indicators (RFC 8707)

Notice the resource=https://mcp.docjacket.com/mcp parameter in the authorization URL. This is RFC 8707 — the access token's aud (audience) claim is bound to this resource URL. A token issued for one MCP server can't be replayed against another (e.g., a stolen Claude.ai token can't be used against a different MCP service).

What we never see

DocJacket never sees or stores:

The contents of conversations you have with your assistant
The internal model the assistant is using
Other tools or connectors the assistant calls

We only see the MCP requests for OUR server: tool name, arguments, latency, outcome. That's it — and it's all in your AI Access activity log.

Need help?

If OAuth fails, the assistant will show a reference ID on the error screen. Send it to support@docjacket.com and we can correlate it with our diagnostic logs (we log every JWT validation failure, every token grant, and every consent decision).

See it in action​

The flow at a glance​

1. Discovery​

2. Dynamic Client Registration (RFC 7591)​

3. Authorize​

4. Consent​

5. Token exchange​

6. Tool calls​

Scopes​

Refresh + rotation​

Revocation​

Resource indicators (RFC 8707)​

What we never see​

Need help?​