> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/the-platform/xyb-platform-overview/platform-authentication.md).

# Platform Authentication

To securely use XYB APIs, you create **entity agents** in the XYB Console that are unique identities that represent your applications or services. You then generate a **public–private key pair** on your own system. Your **private key** stays with you and is used to sign short-lived **JWTs** (JSON Web Tokens). Your **public key** is then **registered in the console** by linking it to an agent. This allows XYB to verify JWTs you sign with your private key and authenticate API requests without sharing secrets over the network.

### **What do you need to do**

To authenticate with XYB APIs, you:

* Create an **agent** in the console which is a unique identity that represents your application or service.
* Generate a **public–private key pair** locally. The **private key** stays with you to sign requests, and the **public key** is what you register with XYB.
* In the console, **register your public key** by creating an API key entry linked to your agent.

***

### How to set up authentication

#### 1. Create an Agent

An *agent* is a unique identity representing your app or service.

1. In the **XYB Console**, go to **Entities**.
2. Click **New entity** and choose **App** (Application role).
3. Fill in:
   * **Name:** Friendly name for your application.
   * **Reference:** Unique identifier for your app.\
     \
     ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-178a98b00cdd79fd3fd326a77ffd0449c68d78f2%2Fimage.png?alt=media)
4. Click **Create entity**.

#### 2. Generate a Key Pair

You must generate a **JWK key pair** (public/private key). Supported types include:

* RSA (e.g. RS256)
* EC (e.g. ES256)
* EdDSA (Ed25519)

Store your **private key** securely.

#### 3. Register your Public Key in the Console

Once you have your public JWK:

1. In the **XYB Console**, go to **API Keys** under **Admin**.
2. Click **+ New key**.
3. Fill in:
   * **Key name:** A label for your tracking (e.g., `Payroll Processor Prod Key`).
   * **Reference:** Auto-generated or custom unique ID for the key.
   * **Agent name:** Select the application entity you created.
   * **Public JWK key:** Paste your public key JSON.\
     ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-b621466ad02fcc9132fa4fff4ee31d68bc07c069%2Fimage.png?alt=media)
4. *(Optional)* You can also **Add expiration date** for when the key will automatically expire. Minimum 3 days from now. If left blank, the key will remain valid until you revoke or rotate it.
5. Click **Create key** and this registers your public key and links it to your agent. XYB can now verify JWTs signed with your private key.

#### 4. Key Rotation and Revocation

You can manage keys directly in the console:

* **Rotate:** Replace the public key without downtime.\
  During rotation, both the old and new keys remain valid for the set **transition period** (e.g., 30 days).\
  ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-8056d25f318f11175a146634dade4b4f469d10c9%2Fimage.png?alt=media)
* **Revoke:** Disable a key instantly if it’s compromised.
* **One active key per agent:** At any given time, only one key is active, except during the rotation period.

All key actions are logged for auditing.

***

### How to Authenticate a Request

Each API request must include:

| Header        | Description                          |
| ------------- | ------------------------------------ |
| Authorization | `Bearer <your signed JWT>`           |
| xyb-agent     | Your registered agent identity       |
| request-id    | *(Optional)* A unique ID for tracing |

**JWT Payload Claims:**

* `sub`: subject of the token
* `iss`: must include the value of `xyb-agent`
* `iat`: issued-at timestamp
* `exp`: expiry timestamp (recommended 5–15 minutes)

**JWT Header Claims:**

* `alg`: algorithm used (e.g., RS256, ES256, EdDSA)
* `kid`: key ID

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/the-platform/xyb-platform-overview/platform-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.