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.

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.

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).

• 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

---