> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Manage API credentials for authentication

## Overview

API credentials are used to authenticate requests to the Gather API. Credentials are scoped to your organization/team and can be created, listed, and revoked.

<Callout type="info">
  Credential management operations are performed via Eucalyptus (internal admin tool). Contact your Qualifi administrator to create or manage API credentials.
</Callout>

## Create API Credentials

Create new API credentials for an organization/team.

**Endpoint:** `POST /qsi/gather/credentials`\
**Access:** Internal via Eucalyptus

<ParamField name="organizationId" type="string" required>
  UUID of the organization
</ParamField>

<ParamField name="teamId" type="string" required>
  UUID of the team
</ParamField>

<ParamField name="name" type="string" required>
  Descriptive name for the API key (e.g., "Production API Key")
</ParamField>

<ParamField name="permissions" type="array" required>
  Array of permission strings: `["read", "write"]`
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "organizationId": "uuid",
    "teamId": "uuid",
    "name": "Production API Key",
    "permissions": ["read", "write"]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "apiKey": "qapi_abc123...",
      "organizationId": "uuid",
      "teamId": "uuid",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

<Callout type="warning">
  The API key is only returned once upon creation. Store it securely. If lost, you'll need to create a new credential.
</Callout>

## List API Credentials

List all API credentials for an organization.

**Endpoint:** `GET /qsi/gather/credentials`\
**Access:** Internal via Eucalyptus

<CodeGroup>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "uuid",
        "name": "Production API Key",
        "organizationId": "uuid",
        "teamId": "uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "lastUsedAt": "2024-01-15T00:00:00Z"
      }
    ],
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Revoke API Credentials

Revoke/delete an API credential.

**Endpoint:** `DELETE /qsi/gather/credentials/{credentialId}`\
**Access:** Internal via Eucalyptus

<ParamField path="credentialId" type="string" required>
  UUID of the credential to revoke
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "id": "uuid",
      "revokedAt": "2024-01-01T00:00:00Z"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

<Callout type="error">
  Revoking a credential immediately invalidates all requests using that API key. Ensure you have alternative credentials before revoking.
</Callout>

## Credential Properties

### API Key Format

API keys are prefixed with `qapi_` followed by a secure random string:

* Example: `qapi_abc123def456ghi789`

### Scope and Permissions

* **Organization Scope**: Credentials are scoped to a specific organization
* **Team Scope**: Credentials can be further scoped to a team within the organization
* **Permission Inheritance**: API keys inherit permissions from the organization/team they're associated with
* **Multiple Keys**: Each organization/team can have multiple API keys

### Security Best Practices

1. **Rotate Regularly**: Rotate API keys periodically for security
2. **Use Separate Keys**: Use different keys for different environments (production, staging)
3. **Monitor Usage**: Regularly review credential usage and revoke unused keys
4. **Secure Storage**: Never commit API keys to version control
5. **Least Privilege**: Use keys with minimal required permissions

## Related Resources

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/getting-started/authentication">
    Learn how to use API credentials for authentication
  </Card>

  <Card title="Best Practices" icon="check-circle" href="/guides/best-practices">
    Review security best practices
  </Card>
</CardGroup>