> For the complete documentation index, see [llms.txt](https://docs.maetra.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maetra.io/govern-api/decision-tokens.md).

# Decision tokens

When a checkpoint reaches a terminal decision, Maetra issues a **decision token** — a signed JWT in `decision_token`. It's cryptographic proof that a specific action was authorised, and it verifies **offline**, without calling back to Maetra.

Use it to gate the action at the point of execution: a downstream service can accept the token, verify it, and be certain the action passed governance.

### Public keys (JWKS)

`GET /.well-known/jwks.json` — **no authentication required.** Returns the key set used to sign decision tokens. Fetch once and cache; the token header's `kid` identifies which key signed it.

{% tabs %}
{% tab title="cURL" %}

```bash
curl "https://api.maetra.io/.well-known/jwks.json" \
  -H "Authorization: Bearer $MAETRA_API_KEY"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const res = await fetch("https://api.maetra.io/.well-known/jwks.json", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = await res.json();
console.log(data);
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const res = await fetch("https://api.maetra.io/.well-known/jwks.json", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = (await res.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

res = requests.get(
    "https://api.maetra.io/.well-known/jwks.json",
    headers={"Authorization": f"Bearer {os.environ['MAETRA_API_KEY']}"},
)
res.raise_for_status()
print(res.json())
```

{% endtab %}

{% tab title="Rust" %}

```rust
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("MAETRA_API_KEY")?;
    let client = reqwest::Client::new();
    let res = client
        .get("https://api.maetra.io/.well-known/jwks.json")
        .bearer_auth(&key)
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{data:#}");
    Ok(())
}
```

{% endtab %}

{% tab title="C++" %}

```cpp
#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = "Authorization: Bearer " + std::string(std::getenv("MAETRA_API_KEY"));
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.maetra.io/.well-known/jwks.json");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);   // response is written to stdout by default
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}
```

{% endtab %}

{% tab title="Java" %}

```java
import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maetra.io/.well-known/jwks.json"))
    .header("Authorization", "Bearer " + System.getenv("MAETRA_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

{% endtab %}
{% endtabs %}

```json
{ "keys": [ { "kty": "EC", "crv": "P-256", "kid": "2026-06", "x": "…", "y": "…" } ] }
```

### Verifying a token

Decision tokens are signed with **ES256** (ECDSA P-256). Verify with any standard JWT library using the JWKS above.

{% tabs %}
{% tab title="JavaScript / TypeScript" %}

```typescript
import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(new URL("https://api.maetra.io/.well-known/jwks.json"));

export async function verifyDecision(token: string) {
  const { payload } = await jwtVerify(token, JWKS);
  if (payload.status !== "approved") {
    throw new Error(`Action not approved: ${payload.status}`);
  }
  return payload; // identifies the checkpoint, action, decision, and expiry
}
```

{% endtab %}

{% tab title="Python" %}

```python
import jwt  # PyJWT
from jwt import PyJWKClient

jwks = PyJWKClient("https://api.maetra.io/.well-known/jwks.json")

def verify_decision(token: str) -> dict:
    key = jwks.get_signing_key_from_jwt(token).key
    payload = jwt.decode(token, key, algorithms=["ES256"])
    if payload.get("status") != "approved":
        raise ValueError(f"Action not approved: {payload.get('status')}")
    return payload
```

{% endtab %}

{% tab title="Go" %}

```go
// Use github.com/lestrrat-go/jwx/v2/jwk + /jwt
keySet, _ := jwk.Fetch(ctx, "https://api.maetra.io/.well-known/jwks.json")
tok, err := jwt.Parse(raw, jwt.WithKeySet(keySet), jwt.WithValidate(true))
if err != nil { /* reject */ }
if status, _ := tok.Get("status"); status != "approved" {
    // do not perform the action
}
```

{% endtab %}
{% endtabs %}

#### What to check

* **Signature** — must validate against a key in the JWKS.
* **`status`** — proceed only when `approved`.
* **Expiry** — reject expired tokens (standard `exp`).
* **Binding** — confirm the token's checkpoint/action matches the action you're about to perform, so a token for one action can't authorise another.

{% hint style="info" %}
Treat the token as a short-lived capability: verify it immediately before acting, not minutes later. The checkpoint's `expires_at` bounds its validity.
{% endhint %}