# Credentials

## Register Credential

Registers a new API credential pair. This endpoint requires **no authentication** — the credential derivation itself serves as proof of authorization.

```
POST /credentials
```

### Request

```json
{
  "api_key": "ak_...",
  "api_secret": "sk_..."
}
```

| Field        | Type   | Required | Description                   |
| ------------ | ------ | -------- | ----------------------------- |
| `api_key`    | String | Yes      | The API key (prefix `ak_`)    |
| `api_secret` | String | Yes      | The API secret (prefix `sk_`) |

### Response — `201 Created`

```json
{
  "api_key": "ak_..."
}
```

### Errors

| HTTP | Code                 | Cause                                               |
| ---- | -------------------- | --------------------------------------------------- |
| 403  | `INVALID_CREDENTIAL` | `api_secret` does not match the expected derivation |
| 409  | `DUPLICATE_API_KEY`  | `api_key` already exists                            |

### How It Works

The endpoint validates that the `api_secret` was correctly derived from the `api_key` using the embedded cryptographic key. Only the vendor can produce valid credential pairs. This is why no authentication is needed — arbitrary key/secret combinations are rejected.

### Example

```bash
curl -X POST http://<host>:8080/credentials \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ak_...", "api_secret": "sk_..."}'
```

***

## Revoke Credential

Revokes an existing API credential. Requires authentication with any valid credential.

```
DELETE /credentials/:api_key
```

### Response — `200 OK`

```json
{
  "api_key": "ak_...",
  "revoked": true
}
```

### Errors

| HTTP | Code                   | Cause                                     |
| ---- | ---------------------- | ----------------------------------------- |
| 401  | `UNAUTHORIZED`         | Missing or invalid authentication headers |
| 404  | `CREDENTIAL_NOT_FOUND` | `api_key` not found or already revoked    |

### Behavior

* Sets the credential to inactive and records the revocation timestamp
* The revoked credential may remain usable for up to **5 minutes** due to auth cache TTL
* Any valid credential can revoke any other credential
* Revocation is permanent — the same `api_key` cannot be reactivated

{% hint style="info" %}
Although not recommended, if the API is unreachable, a credential can be revoked by setting `active = false` directly in the `api_credential` table in the database.
{% endhint %}

### Example

```bash
curl -X DELETE http://<host>:8080/credentials/ak_... \
  -H "X-Api-Key: ak_..." \
  -H "X-Api-Secret: sk_..."
```


---

# 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://entrytarget.gitbook.io/docs/api-reference/credentials.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.