# Token Endpoint

> POST https://webrtc.edesy.in/api/v1/token - exchange your API key for short-lived browser calling credentials. Server-to-server only.

Source: https://edesy.in/docs/webrtc/sdk/token-endpoint

`POST https://webrtc.edesy.in/api/v1/token`

The token endpoint swaps your Edesy API key and a user `identity` for short-lived connection config that the browser SDK uses to register and place calls. Call it only from your server, never from browser code, and pass the JSON response to the page. Each call returns fresh credentials for that identity.

## Request

| Part | Value |
|---|---|
| Method | `POST` |
| URL | `https://webrtc.edesy.in/api/v1/token` |
| Auth header | `x-api-key: YOUR_API_KEY` (or `Authorization: Bearer YOUR_API_KEY`) |
| Body | JSON `{ "identity": "agent-42" }` |

| Field | Type | Required | Description |
|---|---|---|---|
| `identity` | string | yes | Your ID for the user. 1 to 64 characters: letters, digits, `.`, `_`, `@`, `-` |

```bash
curl -X POST https://webrtc.edesy.in/api/v1/token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identity": "agent-42"}'
```

## Response `200`

```json
{
  "server": "wss://...",
  "username": "...",
  "password": "...",
  "callerId": "91XXXXXXXXXX",
  "viaTransport": "WS",
  "iceServers": [{ "urls": "stun:..." }],
  "identity": "agent-42",
  "expiresIn": 3600
}
```

| Field | Description |
|---|---|
| `server` | WebSocket address the SDK registers with |
| `username`, `password` | Short-lived credentials for this identity |
| `callerId` | Caller ID shown on outbound calls |
| `viaTransport` | Transport the SDK uses. Pass it through unchanged |
| `iceServers` | ICE servers for NAT traversal. The SDK applies them to every call |
| `identity` | The identity you sent |
| `expiresIn` | Lifetime of the credentials in seconds |

Pass the whole object to `connect()` without changing it.

## Errors

| Status | Body | Cause |
|---|---|---|
| `401` | `{"error": "invalid api key"}` | Missing or unknown API key |
| `400` | `{"error": "valid 'identity' required"}` | `identity` missing or has characters outside the allowed set |
| `502` | `{"error": "..."}` | Credentials could not be issued. Retry |

## How to use it

1. **Authenticate your user** in your own app first.
2. **Call the endpoint** from your server with your API key and that user's ID as `identity`.
3. **Return the JSON** to the page, either from an endpoint the SDK fetches (`connect("/edesy-token")`) or embedded in a page you render.
4. **Mint again** when `expiresIn` runs out or the device reports an `error`.

## FAQ

### Where do I find my API key?

On the Developers page in [webrtc.edesy.in](https://webrtc.edesy.in). Use Reveal or Copy, and store it as a server environment variable.

### Can the browser call the token endpoint directly?

No. The endpoint needs your API key, which must stay on your server.

### Is the token a JWT?

No. It is a JSON object with connection details and short-lived credentials. Treat it as a secret for that user and do not log it.

### Should I mint one token per page load or per call?

One per session is enough. Call `connect()` once and reuse the device for many calls. Mint a new token when it expires.

### What does `connect("/my-url")` send to my URL?

A `POST` request with no body. Your route should read the user from its own session or cookie.

### How long do credentials last?

The response tells you in `expiresIn`, in seconds.