# Billyou API - OAuth 2.0 (Client Credentials)

## Overview

Billyou supports the **OAuth 2.0 Client Credentials grant** for server-to-server
access, alongside static API keys. Instead of sending a long-lived key on every
request, your backend exchanges a `client_id` + `client_secret` for a
**short-lived Bearer access token** and uses that token to call the API.

This is ideal when you want standards-based OAuth tokens, automatic token
rotation (tokens expire), and the ability to revoke access instantly without
rotating a key your integration has memorised.

**Base URL**: `https://app.billyou.ro/api`

Each OAuth client is scoped to a single organization. Tokens issued for it act
on that organization, exactly like an API key — including rate limits, quota,
and usage tracking.

## 1. Create an OAuth client

Create clients in the Developer Portal under **OAuth Clients**, or via the API
with a normal session/API key. The `client_secret` is shown **once**.

```
POST /api/oauth/clients
Authorization: Bearer <your session JWT>   (or X-API-Key: <key>)
Content-Type: application/json

{ "name": "Acme integration" }
```

Response (`201`):

```json
{
  "success": true,
  "data": {
    "client_id": "bk_id_a1b2c3d4e5f6a1b2c3d4e5f6",
    "client_secret": "bk_cs_…",   // shown once — store securely
    "name": "Acme integration",
    "is_active": true,
    "created_at": "2026-06-26T10:00:00Z"
  }
}
```

Up to **25 active clients per organization**.

## 2. Get an access token

```
POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=bk_id_…&client_secret=bk_cs_…
```

(JSON bodies are also accepted.) Response (`200`):

```json
{ "access_token": "bk_at_…", "token_type": "Bearer", "expires_in": 3600 }
```

Tokens are valid for **1 hour**. There is no refresh token — request a new token
when the current one expires. **Cache the token** and reuse it until it expires;
do not call `/token` on every request.

Errors follow RFC 6749:

- `400 { "error": "unsupported_grant_type" }` — only `client_credentials` is supported.
- `400 { "error": "invalid_request" }` — missing `client_id`/`client_secret`.
- `401 { "error": "invalid_client" }` — unknown client, inactive client, or wrong secret.
- `429 { "error": "invalid_request" }` — too many token requests; slow down.

## 3. Call the API with the token

```
GET /api/invoices
Authorization: Bearer bk_at_…
```

The token resolves to its client's organization. All standard endpoints accept
it. Requests are metered against your organization's API quota and rate limits,
the same as API-key requests.

## 4. Manage clients

```
GET    /api/oauth/clients                     # list (no secrets)
POST   /api/oauth/clients/{clientId}/rotate   # new secret (shown once); old secret stops working
DELETE /api/oauth/clients/{clientId}          # delete client AND revoke its live tokens
GET    /api/oauth/clients/{clientId}/usage    # request count, error rate, avg latency, last used
```

Rotating a secret does **not** invalidate already-issued access tokens — they
expire on their own within the hour. Deleting a client revokes its live tokens
immediately.

## OAuth vs API keys — which to use?

- **API key** (`bk_user_…`): simplest; one header, never expires (unless you set
  an expiry). Good for quick integrations and scripts.
- **OAuth client credentials**: standards-based; short-lived tokens, instant
  revocation, per-client usage analytics. Good for production server-to-server
  integrations and tooling that already speaks OAuth.

Both authenticate as your organization with the same permissions. OAuth does not
add scopes — a token has the same access as an API key.

## Notes

- Secrets and tokens are stored **hashed**; Billyou cannot show them again.
- Always send tokens over HTTPS.
- The token endpoint is rate-limited per IP to deter secret brute-forcing.
