> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/consumers/credentials-groups.md).

# Credentials, groups, and policies

Managed credentials bind approved client authentication material to a consumer. Consumer groups provide tenant-owned names for ACL and scoped policy selection.

## Credential API

| Operation             | Endpoint                                                           |
| --------------------- | ------------------------------------------------------------------ |
| Create                | `POST /api/v1/admin/consumer-credentials`                          |
| List for one consumer | `GET /api/v1/admin/consumer-credentials?consumer_id={consumer_id}` |
| Delete                | `DELETE /api/v1/admin/consumer-credentials/{credential_id}`        |

Create requests include `consumer_id`, `type`, type-specific `key` and `secret` values, optional `tenant_id`, and optional `expires_at` or `ttl_seconds`. Supply only one expiry field.

## Supported credential types

| Type      | Required values                                | Runtime use                                                                   | Replacement                                                                |
| --------- | ---------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `api_key` | High-entropy `key`                             | Send in `X-API-Key` and attach `api_key_auth`.                                | Create a new key, deploy it to the client, then delete the old credential. |
| `basic`   | Username as `key`, strong password as `secret` | Send with HTTP Basic over TLS and enforce consumer group membership with ACL. | Create new credentials, update the client, then delete the old credential. |

### Create a Basic credential

```bash
curl -X POST "$KANGAL_ADMIN_URL/api/v1/admin/consumer-credentials" \
  -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "consumer_id": "CONSUMER_ID",
    "type": "basic",
    "key": "orders-client",
    "secret": "REPLACE_WITH_A_STRONG_PASSWORD",
    "tenant_id": "tenant-a",
    "ttl_seconds": 2592000
  }'
```

## Credential security

* Generate API keys and passwords with an approved high-entropy generator.
* Store client credentials in a secret manager and send them only over TLS.
* Treat create and list responses as sensitive; do not write them to logs or support tickets.
* API-key values are encrypted at rest. Basic passwords are stored as non-reversible password hashes.
* Credential keys are unique within a tenant and credential type.
* Use `expires_at` or `ttl_seconds` to enforce credential lifetime.
* Delete superseded credentials after clients have moved to the replacement.

## Consumer-group API

| Operation         | Endpoint                                                                  |
| ----------------- | ------------------------------------------------------------------------- |
| Create/list       | `POST`, `GET /api/v1/admin/consumer-groups`                               |
| Get/update/delete | `GET`, `PATCH`, `DELETE /api/v1/admin/consumer-groups/{group_id}`         |
| Add member        | `POST /api/v1/admin/consumer-groups/{group_id}/consumers/{consumer_id}`   |
| Remove member     | `DELETE /api/v1/admin/consumer-groups/{group_id}/consumers/{consumer_id}` |

A group requires `tenant_id` and a tenant-unique `name`. `description` and `tags` are optional.

```bash
curl -X POST "$KANGAL_ADMIN_URL/api/v1/admin/consumer-groups" \
  -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant-a",
    "name": "payments",
    "description": "Payment API clients",
    "tags": ["production"]
  }'
```

Assign a consumer to the group:

```bash
curl -X POST \
  "$KANGAL_ADMIN_URL/api/v1/admin/consumer-groups/GROUP_ID/consumers/CONSUMER_ID" \
  -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN"
```

The group and consumer must belong to the same tenant. Membership uses the group name consumed by `acl_control` and `scope: "consumer_group"` policies.

## Rename or delete a group

Update memberships as part of every rename or deletion:

1. list members with `GET /api/v1/admin/consumers?group={current_name}`;
2. remove each member through the group membership endpoint;
3. rename or delete the group;
4. after a rename, assign the consumers to the renamed group.

Use managed group entities and membership endpoints for production ACLs. Apply a consistent naming standard across environments.

## Troubleshooting

| Symptom                                | Check                                                                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| API key is rejected                    | Verify the exact `X-API-Key` value, expiry, tenant, consumer, and attached `api_key_auth` policy. |
| Basic credential is rejected           | Verify the username and password, expiry, tenant ownership, TLS, and the consumer's ACL group.    |
| Group assignment returns an error      | Verify the group and consumer IDs and confirm both resources belong to the same tenant.           |
| ACL does not recognize a renamed group | Complete the membership removal and reassignment workflow with the current group name.            |


---

# 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.kangal.dev/consumers/credentials-groups.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.