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

# Credentials

> Securely manage connection credentials.

Use the credentials API to create, update, and retire stored connection profiles (cloud, database, API keys, OAuth, and passwords). Responses return **metadata only**—secret values are never echoed back in list or get operations.

Authenticate every request with your API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY_HERE
```

<Info>
  If your workspace uses URL versioning, insert `/v1` before `/api` in the path (for example `https://api.planasonix.com/v1/api/credentials`). See [API reference](/api-reference/introduction).
</Info>

## List credentials

```http theme={null}
GET https://api.planasonix.com/api/credentials
```

Returns credential records your key can access. Fields such as passwords, tokens, and private keys are omitted; you see names, types, status, and non-sensitive configuration hints.

```json theme={null}
{
  "data": [
    {
      "id": "cred_01j9k2m4n5p6q7r8",
      "name": "prod-snowflake-reader",
      "type": "database",
      "status": "active",
      "created_at": "2025-03-20T09:15:22Z",
      "updated_at": "2025-03-26T14:02:11Z",
      "created_by": "usr_01h8abc",
      "config": {
        "host": "xy12345.us-east-1.snowflakecomputing.com",
        "warehouse": "COMPUTE_WH",
        "database": "analytics",
        "role": "READER_ROLE",
        "username": "svc_planasonix"
      }
    },
    {
      "id": "cred_01j9k3x7y8z9a0b1",
      "name": "marketing-s3-bucket",
      "type": "aws",
      "status": "active",
      "created_at": "2025-03-18T11:40:00Z",
      "updated_at": "2025-03-18T11:40:00Z",
      "config": {
        "region": "us-east-1",
        "role_arn": "arn:aws:iam::123456789012:role/PlanasonixIngest"
      }
    }
  ],
  "meta": {
    "page": { "limit": 50, "cursor": null }
  }
}
```

## Create credential

```http theme={null}
POST https://api.planasonix.com/api/credentials
Content-Type: application/json
```

| Field    | Type   | Description                                                              |
| -------- | ------ | ------------------------------------------------------------------------ |
| `name`   | string | Human-readable label unique within the workspace                         |
| `type`   | string | One of `aws`, `azure`, `gcp`, `database`, `api_key`, `oauth`, `password` |
| `config` | object | Type-specific settings; secret fields are stored encrypted server-side   |

```json theme={null}
{
  "name": "staging-postgres-etl",
  "type": "database",
  "config": {
    "engine": "postgresql",
    "host": "db.internal.example.com",
    "port": 5432,
    "database": "staging",
    "username": "planasonix_etl",
    "password": "use-a-strong-secret-here"
  }
}
```

```json theme={null}
{
  "data": {
    "id": "cred_01j9k4c2d3e4f5g6",
    "name": "staging-postgres-etl",
    "type": "database",
    "status": "active",
    "created_at": "2025-03-27T10:00:00Z",
    "updated_at": "2025-03-27T10:00:00Z",
    "config": {
      "engine": "postgresql",
      "host": "db.internal.example.com",
      "port": 5432,
      "database": "staging",
      "username": "planasonix_etl"
    }
  }
}
```

## Get credential metadata

```http theme={null}
GET https://api.planasonix.com/api/credentials/{id}
```

Path parameter `id` is the credential identifier (for example `cred_01j9k2m4n5p6q7r8`).

```json theme={null}
{
  "data": {
    "id": "cred_01j9k2m4n5p6q7r8",
    "name": "prod-snowflake-reader",
    "type": "database",
    "status": "active",
    "created_at": "2025-03-20T09:15:22Z",
    "updated_at": "2025-03-26T14:02:11Z",
    "config": {
      "host": "xy12345.us-east-1.snowflakecomputing.com",
      "warehouse": "COMPUTE_WH",
      "database": "analytics",
      "role": "READER_ROLE",
      "username": "svc_planasonix"
    }
  }
}
```

## Update credential

```http theme={null}
PUT https://api.planasonix.com/api/credentials/{id}
Content-Type: application/json
```

Send the fields you want to change. Omitted fields are left unchanged unless the API documentation for your deployment states otherwise.

```json theme={null}
{
  "name": "prod-snowflake-reader-v2",
  "config": {
    "warehouse": "ETL_WH",
    "role": "ETL_ROLE"
  }
}
```

## Soft-delete credential

```http theme={null}
DELETE https://api.planasonix.com/api/credentials/{id}
```

Marks the credential as deleted. Pipelines that still reference it may fail until you attach a different credential or restore this one.

```json theme={null}
{
  "data": {
    "id": "cred_01j9k2m4n5p6q7r8",
    "status": "deleted",
    "deleted_at": "2025-03-27T16:45:00Z"
  }
}
```

## Restore deleted credential

```http theme={null}
POST https://api.planasonix.com/api/credentials/{id}/restore
```

```json theme={null}
{
  "data": {
    "id": "cred_01j9k2m4n5p6q7r8",
    "status": "active",
    "deleted_at": null
  }
}
```

## Permanently delete credential

```http theme={null}
DELETE https://api.planasonix.com/api/credentials/{id}/permanent
```

<Warning>
  This action cannot be undone. Ensure no pipelines or schedules reference this credential before calling permanent delete.
</Warning>

```json theme={null}
{
  "data": {
    "id": "cred_01j9k2m4n5p6q7r8",
    "purged": true
  }
}
```

## Related topics

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API keys and Bearer tokens.
  </Card>

  <Card title="Credentials (UI)" icon="plug" href="/connections/credentials">
    How credentials work in the product.
  </Card>
</CardGroup>