# Authentication

## Creating an API key

To use the Legion API, you must request a key from the Legion team. After being approved, you will receive the API key associated with your credential. 

The API key obtained from the credentials portal will be used as the `x-api-key` header you will need to pass during authentication when calling our API endpoints. 

## Request and Webhook Signature Verification

To ensure the security and integrity of communication between your application and our platform, all API requests must be signed. Additionally, all webhooks sent from our system will be signed using HMAC and included in the request headers.

### Getting Your Secret Signing Key

📩 Contact the Legion team to request your unique signing key. 

> This key must be kept confidential and never shared publicly.

### Signing API Requests

All API requests to our platform must be signed using `HMAC` with `SHA-256`. 

* For `POST` requests: The signature must be computed using the request body.
* For `GET` requests: The signature must be computed using a unique identifier (e.g., user\_id or round\_id).

Steps for signing requests: 

1. Construct the Signing String:
   * `POST requests`: Use the raw request body.
   * `GET requests`: Use the primary identifier (e.g., user\_id, round\_id). 
2. Generate the HMAC Signature:
   * Use your secret key to compute an `HMAC` signature with `SHA-256`.
3. Attach the Signature to the Request Header: 
   * Include the computed signature in the `X-Signature` header.

Example Header:

```
X-Signature: <generated_signature>
```

### Webhook Signature Verification

All webhook events sent from our platform will be signed using `HMAC` and included in the `X-Signature` header.

Steps to verify webhooks:&#x20;

1. Retrieve the signature from the header, webhook requests will contain `X-Signature` header:

```
X-Signature: <hmac_signature>
```

2. Recompute the signature - use your secret signing key and compute an `HMAC-SHA256` signature using the raw request body.
3. Compare signatures - if the computed signature matches the received `X-Signature`, the webhook is authentic.


---

# Agent Instructions: 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:

```
GET https://legion-1.gitbook.io/legion/backend/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.