Authentication

Getting access

1. Get appointed. Your agency signs a broker agreement with Valjean (valjeanspecialty.com, Get Appointed).
2. Open your portal. Your Valjean broker sends a private link to your agency portal.
3. Make a key. In the portal, under API keys, name the key and choose read or read-and-submit. Or connect an AI assistant or the CLI by signing in; you approve it in the portal.

Read-only keys work right away; submitting starts once the broker agreement is signed.

API keys

Keys look like vjk_live_… (your real book) or vjk_demo_… (the sandbox). Get them from your agency portal or your Valjean broker. A key is shown once: store it like a password.

Send it as a bearer token, or in an X-Api-Key header for tools that can’t set Authorization:

curl https://api.valjeanspecialty.com/api/agent/v1/me -H "Authorization: Bearer vjk_demo_..."

Scopes

Scope	Can do
Read	Appetite, requirements, status, quotes, documents, policies, invoices, events, webhooks
Read and submit	Also send files, answers, documents, bind requests and instant-quote asks

Submitting also needs a signed broker agreement with Valjean. Without one, submit calls return 403 agency_not_active even with a read-and-submit key. GET /me tells you what a key can do (can_submit).

A key sees only your own agency’s files. It never sees market names before a quote is presented, rates, commissions, internal notes or other agencies.

Sign-in for AI apps (OAuth)

Apps that connect by signing in, such as a chat app’s custom connector, use OAuth 2.1:

• Discovery: https://api.valjeanspecialty.com/.well-known/oauth-authorization-server (and /.well-known/oauth-protected-resource for the MCP server).
• Dynamic client registration at /oauth/register; public clients, no client secret.
• Authorization code flow with PKCE (S256 only). You approve in the browser with your portal link or an API key, and choose read or read-and-submit.
• Access tokens (vjat_…) last 1 hour. Refresh tokens last 30 days and rotate on every use. Revoke with POST /oauth/revoke.

Tokens work everywhere a key does, with the scope you approved.

Sign-in from a terminal (device code)

For tools with no browser of their own, such as the CLI, Valjean supports the OAuth device flow (RFC 8628):

1. POST /oauth/device_authorization with client_id=vjc_cli (or your registered client). You get a device_code, a user_code like WDJB-MJHT, a verification_uri and an interval.
2. Show the person the code and link. They open /oauth/device, check the code, and approve with their portal link or an API key.
3. Poll POST /oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code, the device_code and client_id, every interval seconds. You get authorization_pending until they approve, slow_down if you poll too fast (add 5 seconds), access_denied if they decline, and expired_token after 10 minutes.

The tokens are the same vjat_… / vjrt_… pair as above, with the same lifetimes.

Revoking access

• A key: revoke it in your agency portal (or ask your broker). It stops working at once.
• A connected app: turn it off under Connected apps in your portal.
• Revoking a key or a portal link also signs out every app that was approved with it.

Caution

Keys expire (30, 90 or 365 days, or never when your broker sets it). Calls with an expired or revoked key return 401 unauthorized: don’t retry, get a new key.