# Credential Management

API credentials are how your application authenticates with EntryTarget. This page covers the full credential lifecycle.

## How Credentials Work

Each credential consists of two parts:

| Component      | Prefix | Purpose                        |
| -------------- | ------ | ------------------------------ |
| **API Key**    | `ak_`  | Identifies your application    |
| **API Secret** | `sk_`  | Authenticates your application |

The API secret is cryptographically derived from the API key — it is not a random string. This derivation is performed by the vendor Console using a key derived at runtime from secrets embedded in the ledger binary. Only the vendor can produce valid credential pairs.

## Credential Lifecycle

### 1. Generate in the Console

Generate a new API key pair in the vendor Console:

1. Log in to `https://console.entrytarget.com/`
2. Navigate to your ledger instance
3. Click "Generate Credentials"
4. Copy the `api_key` and `api_secret`

{% hint style="warning" %}
Save the `api_secret` immediately. It will not be shown again.
{% endhint %}

### 2. Register on Your Ledger

Register the credential pair on your ledger instance:

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

This endpoint requires **no authentication** — the cryptographic derivation of the `api_secret` serves as proof that the credential was generated by someone with access to the key.

### 3. Use in API Calls

Include both values in every authenticated API request:

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

### 4. Revoke When Needed

Revoke a credential via the API (requires authentication with any valid credential):

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

## Multiple Credentials

You can have multiple active API key pairs. Common patterns:

### Credential Rotation

1. Generate a new credential pair
2. Register it on the ledger
3. Update your application to use the new credentials
4. Revoke the old credentials

### Environment Separation

* One credential for production services
* One credential for monitoring/auditing tools
* One credential for manual testing

### Team Access

* Different credentials for different teams or services
* Revoke individually without affecting others

## Security Best Practices

* **Never share API secrets** in logs, version control, or unencrypted channels
* **Rotate credentials** periodically (e.g., quarterly)
* **Revoke immediately** if a credential is compromised
* **Use separate credentials** for different environments and services
* **Store credentials** in a secrets manager (e.g., AWS Secrets Manager)

## Revocation Notes

* After revoking a credential, it may remain valid for up to **5 minutes** due to the authentication cache TTL
* Any valid credential can revoke any other credential
* Revocation is permanent — the same `api_key` cannot be reactivated
* If the API is unreachable, you can revoke directly in the database by setting `active = false` on the `api_credential` table (not recommended for normal operations)

## Troubleshooting

### 401 Unauthorized

* Verify both `X-Api-Key` and `X-Api-Secret` headers are present
* Check that the credential is registered on this ledger instance
* Check that the credential has not been revoked

### 403 Invalid Credential (on registration)

* The `api_secret` does not match the expected derivation
* Ensure the credential was generated by the Console for this specific ledger instance
* Credentials from one ledger instance cannot be used on another

### 409 Duplicate API Key

* The `api_key` is already registered
* Each `api_key` can only be registered once


---

# 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/console/credential-management.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.