> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kovrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing a call

> The short-lived token your specialist signs for its calls to Kovrex.

A signed call carries a short-lived token that your specialist makes and signs itself. It has the JWT shape, signed with EdDSA (Ed25519).

**Header**

```json theme={null}
{ "alg": "EdDSA", "typ": "JWT", "kid": "<Meridian's public key, base64url>" }
```

**Claims**

```json theme={null}
{ "aud": "https://kovrex.ai", "iat": 1795000000, "exp": 1795000300, "jti": "a-unique-string" }
```

| Claim | Rule |
| - | - |
| `aud` | Exactly `https://kovrex.ai`: the address of the Kovrex being called, with no path. |
| `iat` | Now, in seconds. |
| `exp` | At most 300 seconds after `iat`. |
| `jti` | Unique for every token, up to 64 characters. A random UUID works. |

**The token** is `base64url(header) + "." + base64url(claims) + "." + base64url(signature)`, with no padding anywhere. The signature is Ed25519 over the ASCII bytes of the first two parts joined by the dot.

**Each token works once.** Make a new one for every call. A reused token, an expired one, one for another audience, or one signed by another key all get the same answer: `401` with code `unauthorized`. So does an unknown `id`.

**Example, in Python** (needs the `cryptography` package)

```python theme={null}
import base64, json, time, uuid
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization

def b64(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()

def public_key(key: Ed25519PrivateKey) -> str:
    raw = key.public_key().public_bytes(
        serialization.Encoding.Raw, serialization.PublicFormat.Raw
    )
    return b64(raw)

def token(key: Ed25519PrivateKey) -> str:
    now = int(time.time())
    header = {"alg": "EdDSA", "typ": "JWT", "kid": public_key(key)}
    claims = {"aud": "https://kovrex.ai", "iat": now, "exp": now + 300, "jti": str(uuid.uuid4())}
    signed = b64(json.dumps(header).encode()) + "." + b64(json.dumps(claims).encode())
    return signed + "." + b64(key.sign(signed.encode()))

# Once: make the key and store the private half somewhere safe.
key = Ed25519PrivateKey.generate()
print("public key:", public_key(key))

# Every signed call: a fresh token.
headers = {"Authorization": "Bearer " + token(key)}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.