API key or OAuth 2.0?
Both lead to the same endpoints under /api/v1
API key
For your own software and your own account. You create the key in the dashboard and send it in the X-Api-Key header. An API key may use all endpoints. Authentication with an API key
OAuth 2.0
For apps and agents that work for other briefsenden accounts. Every user consents in the browser, sees the requested permissions and can revoke access at any time.
Flow: authorization code with PKCE
From registration to the first API call
The API supports the authorization code flow for public clients: there is no client secret, and PKCE is required; use S256. All addresses are under https://www.briefsenden.com.
Find the addresses
Every
401response of the API gives the address of the metadata in theWWW-Authenticateheader (resource_metadata, RFC 9728). It leads to the authorization server, whose metadata (RFC 8414) lists all endpoints and the scopes.cURLcurl https://www.briefsenden.com/.well-known/oauth-protected-resource/api/v1 curl https://www.briefsenden.com/.well-known/oauth-authorization-server
Register your app
Your app registers itself once (RFC 7591) and receives a
client_id.redirect_uristakes 1 to 10 addresses:https,httponly on the local machine (localhost), or a private app scheme such asmyapp://callback. The user sees theclient_nameon the consent page.cURLcurl -X POST https://www.briefsenden.com/api/oauth/register \ -H "Content-Type: application/json" \ -d '{"client_name": "Demo-App", "redirect_uris": ["https://app.example.com/callback"]}' # 201 Created { "client_id": "0f8fad5bd9cb469fa16570867728950e", "client_name": "Demo-App", "redirect_uris": ["https://app.example.com/callback"], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "token_endpoint_auth_method": "none", "scope": "letters:read letters:write balance:read …", "client_id_issued_at": 1794441600 }Ask for consent
Create a
code_verifierandcode_challengeand open this address in the user’s browser. They sign in to briefsenden.com, see the app, the redirect target and the permissions, and decide. The browser then returns to yourredirect_uriwithcodeandstate, or witherror=access_deniedif they deny. Withoutscope, the app asks for all permissions.Browserhttps://www.briefsenden.com/api/oauth/authorize ?response_type=code &client_id=0f8fad5bd9cb469fa16570867728950e &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback &scope=letters%3Awrite%20balance%3Aread &state=af0ifjsldkj &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 &resource=https%3A%2F%2Fwww.briefsenden.com%2Fapi%2Fv1
Exchange the code for tokens
Send the
codetogether with thecode_verifierto the token endpoint. The response contains theaccess_token, its lifetime in seconds (expires_in) and always arefresh_token.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=authorization_code \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d redirect_uri=https://app.example.com/callback \ -d code=CODE \ -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \ -d resource=https://www.briefsenden.com/api/v1
Call the API
Send the access token in the
Authorizationheader tohttps://www.briefsenden.com/api/v1. Endpoints, error format and webhooks are the same as with an API key, see the API documentation. Rate limit and idempotency keys count per grant.cURLcurl https://www.briefsenden.com/api/v1/balance \ -H "Authorization: Bearer ACCESS_TOKEN"
Refresh the token
Once the access token has expired, the API answers with
401. Use the refresh token to get a new one without the user consenting again. If the response contains a newrefresh_token, use that one from then on.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=refresh_token \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d refresh_token=REFRESH_TOKEN \ -d resource=https://www.briefsenden.com/api/v1
Agents without a browser: registration and claim
The agent registers itself, the user connects it with a code
An agent without its own browser and without a redirect address uses agent registration as described in auth.md: it registers anonymously, shows the user a link and a code, and the user connects the agent to their account on briefsenden.com (device flow, RFC 8628). Before this connection the agent can only estimate costs; it triggers neither printing nor costs. The machine-readable version is at /auth.md.
Register the agent
The agent registers without signing in and without
redirect_uris. The response containsclient_idandclient_secret; the secret appears only in this response and belongs in every further request of the agent. The user later sees theclient_nameon the "Connect an agent" page; it must not contain the name briefsenden. Registrations are rate limited: on429,Retry-Aftergives the waiting time.cURLcurl -X POST https://www.briefsenden.com/api/oauth/agent/register \ -H "Content-Type: application/json" \ -d '{"client_name": "Demo-Agent"}' # 201 Created { "client_id": "0f8fad5bd9cb469fa16570867728950e", "client_secret": "CLIENT_SECRET", "client_name": "Demo-Agent", "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token", "client_credentials"], "token_endpoint_auth_method": "client_secret_post", "scope": "letters:read letters:write balance:read …", "client_id_issued_at": 1794441600, "client_secret_expires_at": 0 }Before the connection: cost estimates only
With
grant_type=client_credentialsthe agent receives a token without an account. It is valid only forPOST /estimateandPOST /serial/estimate; every other endpoint answers with403. Reuse the token until it expires (expires_in): each agent may request 10 tokens in 10 minutes. This step is optional.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=client_credentials \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d client_secret=CLIENT_SECRET curl -X POST https://www.briefsenden.com/api/v1/estimate \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"pages": 2}'Request a code and link
The agent requests a code.
scopeis required: it names only the scopes it needs. It shows the user theverification_uriand theuser_code. The user opens the link, signs in, types the code themselves, sees the name of the agent and the permissions, and connects or denies. After connecting, the account holder receives an email with the name of the agent and where to revoke the access. The code is valid for 10 minutes (expires_in); each agent may request 5 codes in 10 minutes.cURLcurl -X POST https://www.briefsenden.com/api/oauth/device \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d client_secret=CLIENT_SECRET \ -d "scope=letters:write balance:read" # 200 OK { "device_code": "DEVICE_CODE", "user_code": "1234-5678-9012", "verification_uri": "https://www.briefsenden.com/api/oauth/claim", "interval": 5, "expires_in": 600 }Wait for the decision
The agent polls the token endpoint at the
interval(5 seconds) with thedevice_code. As long as the user has not decided, the answer isauthorization_pending; if it polls too fast,slow_down; after a denial,access_denied. After the connection it contains theaccess_tokenandrefresh_tokenfor the granted scopes; from then on the steps "Call the API" and "Refresh the token" above apply, each with theclient_secret. If the code has expired (expired_token), the agent requests a new one.cURLcurl -X POST https://www.briefsenden.com/api/oauth/token \ -d grant_type=urn:ietf:params:oauth:grant-type:device_code \ -d device_code=DEVICE_CODE \ -d client_id=0f8fad5bd9cb469fa16570867728950e \ -d client_secret=CLIENT_SECRET # 400 Bad Request { "error": "authorization_pending" } # 200 OK { "access_token": "…", "token_type": "Bearer", "expires_in": …, "refresh_token": "…" }
Scopes
Permissions the user grants
A scope ending in :read applies to GET, a scope ending in :write to all other methods. balance:read also covers cost estimates. If the token lacks the scope of an endpoint, the API answers with 403 and names it in the WWW-Authenticate header (error="insufficient_scope").
| Scope | Allows | Endpoints under /api/v1 |
|---|---|---|
| letters:read | View letters and mail merges | GET /letters, /letters/{id}, /serial, /serial/{id}, /serial/{id}/letters |
| letters:write | Send letters and cancel mail merges | POST /letters, /letters/structured, /letters/simple, /letters/bulk · DELETE /serial/{id} |
| balance:read | View the balance and estimate costs | GET /balance · POST /estimate, /serial/estimate |
| sender-profiles:read | View sender profiles | GET /sender-profiles |
| sender-profiles:write | Create, change and delete sender profiles | POST, PUT, DELETE /sender-profiles |
| addresses:read | View the address book | GET /addresses |
| addresses:write | Create, change and delete addresses | POST, PUT, DELETE /addresses |
| webhooks:read | View webhooks | GET /webhooks |
| webhooks:write | Create and delete webhooks | POST, DELETE /webhooks |
OAuth endpoints
Addresses of the authorization server
| Method | Endpoint | Description |
|---|---|---|
| GET | /.well-known/oauth-protected-resource/api/v1 | Metadata of the API: authorization server and scopes (RFC 9728) |
| GET | /.well-known/oauth-authorization-server | Metadata of the authorization server: all endpoints (RFC 8414) |
| POST | /api/oauth/register | Register an app (RFC 7591) |
| GET | /api/oauth/authorize | User consent in the browser |
| POST | /api/oauth/agent/register | Register an agent without a browser (auth.md) |
| POST | /api/oauth/device | Request a code and link for the connection (RFC 8628) |
| GET | /api/oauth/claim | "Connect an agent" page: the user types the code |
| POST | /api/oauth/token | Exchange a code, device code or refresh token for tokens |
| POST | /api/oauth/revoke | Revoke a token (RFC 7009) |
Test mode and costs
OAuth tokens have no test and live switch of their own like the API keys (bv_test_…, bv_live_…). Letters follow the test mode of the account: in test mode they are not printed and cost no Coins, otherwise they are printed, sent and paid for with Coins. If the app may send letters, the consent page tells the user beforehand which applies.
Revoking access
The user can revoke access at any time under Settings → Developer → Connected apps. Access and refresh tokens then stop working from the next request. There is one grant per app and account: if the user consents to the same app again, the new grant replaces the old one including its tokens. Agents that were never connected to an account are deleted one day after registration at the earliest, apps without any consent after 7 days at the earliest; they register again when needed. Apps and agents that were connected once stay registered, also after a revocation.
Endpoints, webhooks, error format and Swagger UI: go to the API documentation .
Integrate now
Create a free account and try the OAuth flow in test mode, without a letter being printed.