API v1

OAuth 2.0 for the letter API

With OAuth 2.0, apps and agents access the API on behalf of a briefsenden account: the account holder signs in and grants access themselves. Your app receives an access token with exactly the permissions granted, never a password or API key.

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.

  1. Find the addresses

    Every 401 response of the API gives the address of the metadata in the WWW-Authenticate header (resource_metadata, RFC 9728). It leads to the authorization server, whose metadata (RFC 8414) lists all endpoints and the scopes.

    cURL
    curl https://www.briefsenden.com/.well-known/oauth-protected-resource/api/v1
    curl https://www.briefsenden.com/.well-known/oauth-authorization-server
  2. Register your app

    Your app registers itself once (RFC 7591) and receives a client_id. redirect_uris takes 1 to 10 addresses: https, http only on the local machine (localhost), or a private app scheme such as myapp://callback. The user sees the client_name on the consent page.

    cURL
    curl -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
    }
  3. Ask for consent

    Create a code_verifier and code_challenge and 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 your redirect_uri with code and state, or with error=access_denied if they deny. Without scope, the app asks for all permissions.

    Browser
    https://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
  4. Exchange the code for tokens

    Send the code together with the code_verifier to the token endpoint. The response contains the access_token, its lifetime in seconds (expires_in) and always a refresh_token.

    cURL
    curl -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
  5. Call the API

    Send the access token in the Authorization header to https://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.

    cURL
    curl https://www.briefsenden.com/api/v1/balance \
      -H "Authorization: Bearer ACCESS_TOKEN"
  6. 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 new refresh_token, use that one from then on.

    cURL
    curl -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.

  1. Register the agent

    The agent registers without signing in and without redirect_uris. The response contains client_id and client_secret; the secret appears only in this response and belongs in every further request of the agent. The user later sees the client_name on the "Connect an agent" page; it must not contain the name briefsenden. Registrations are rate limited: on 429, Retry-After gives the waiting time.

    cURL
    curl -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
    }
  2. Before the connection: cost estimates only

    With grant_type=client_credentials the agent receives a token without an account. It is valid only for POST /estimate and POST /serial/estimate; every other endpoint answers with 403. Reuse the token until it expires (expires_in): each agent may request 10 tokens in 10 minutes. This step is optional.

    cURL
    curl -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}'
  3. Request a code and link

    The agent requests a code. scope is required: it names only the scopes it needs. It shows the user the verification_uri and the user_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.

    cURL
    curl -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
    }
  4. Wait for the decision

    The agent polls the token endpoint at the interval (5 seconds) with the device_code. As long as the user has not decided, the answer is authorization_pending; if it polls too fast, slow_down; after a denial, access_denied. After the connection it contains the access_token and refresh_token for the granted scopes; from then on the steps "Call the API" and "Refresh the token" above apply, each with the client_secret. If the code has expired (expired_token), the agent requests a new one.

    cURL
    curl -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").

ScopeAllowsEndpoints under /api/v1
letters:readView letters and mail mergesGET /letters, /letters/{id}, /serial, /serial/{id}, /serial/{id}/letters
letters:writeSend letters and cancel mail mergesPOST /letters, /letters/structured, /letters/simple, /letters/bulk · DELETE /serial/{id}
balance:readView the balance and estimate costsGET /balance · POST /estimate, /serial/estimate
sender-profiles:readView sender profilesGET /sender-profiles
sender-profiles:writeCreate, change and delete sender profilesPOST, PUT, DELETE /sender-profiles
addresses:readView the address bookGET /addresses
addresses:writeCreate, change and delete addressesPOST, PUT, DELETE /addresses
webhooks:readView webhooksGET /webhooks
webhooks:writeCreate and delete webhooksPOST, DELETE /webhooks

OAuth endpoints

Addresses of the authorization server

MethodEndpointDescription
GET/.well-known/oauth-protected-resource/api/v1Metadata of the API: authorization server and scopes (RFC 9728)
GET/.well-known/oauth-authorization-serverMetadata of the authorization server: all endpoints (RFC 8414)
POST/api/oauth/registerRegister an app (RFC 7591)
GET/api/oauth/authorizeUser consent in the browser
POST/api/oauth/agent/registerRegister an agent without a browser (auth.md)
POST/api/oauth/deviceRequest 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/tokenExchange a code, device code or refresh token for tokens
POST/api/oauth/revokeRevoke 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 .

Free test mode – no credit card needed

Integrate now

Create a free account and try the OAuth flow in test mode, without a letter being printed.

No base fee No minimum order Pay per letter