# Provider credentials
URL: https://openship.io/docs/api/credentials.md

Store and verify organization-owned registry and DNS credentials.

Provider credentials let Openship pull private images or update DNS. A credential belongs to one
organization. Reads expose public fields and masked secret indicators; creating, changing, verifying,
or removing a credential requires administration access.

## Discover supported providers

Read provider definitions before building a credential form. Each definition includes its ID, capability,
selector requirements, and field keys. Use those keys in the `values` object when creating a credential.

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
const providers = await ship.credentials.listProviders();
console.log(providers);
```

</Tab>
<Tab value="REST API">

```bash
curl "$OPENSHIP_URL/api/credentials/providers" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"
```

</Tab>
</Tabs>

## Create or update a credential

| Field | Type | Use |
| --- | --- | --- |
| `provider` | `string` | Required on creation; an ID from the provider catalog, at most 64 characters. |
| `name` | `string` | Required on creation; a display name of 1–100 characters. |
| `selector` | `string` or `null` | Provider-specific registry or account selector. |
| `values` | `Record<string, string>` | Required on creation; public and secret fields defined by the provider. |

Updates accept `name`, `selector`, and `values`. The provider cannot be changed. Use values from your
credential form or secret store; masked values returned by reads are not replacement secrets.

## Verify a saved credential

<Tabs items={['SDK', 'REST API']} groupId="api-transport" persist>
<Tab value="SDK">

```ts
const credential = await ship.credentials.verify("cred_123");
console.log(credential.status, credential.lastError);
```

</Tab>
<Tab value="REST API">

```bash
curl -X POST "$OPENSHIP_URL/api/credentials/cred_123/verify" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"
```

</Tab>
</Tabs>

Verification returns the credential's status, `lastVerifiedAt`, and `lastError`. Check that status before
using the credential for a deployment. See [DNS providers](/docs/api/dns) for the DNS connection workflow.

## Operations

{/* api-operations:start */}

| Operation | SDK | REST API |
| --- | --- | --- |
| List provider credential types and required fields. | `credentials.listProviders()` | `GET /api/credentials/providers`<br />`settings:read` |
| List stored credentials with secrets masked. | `credentials.list()` | `GET /api/credentials`<br />`settings:read` |
| Store a provider credential. | `credentials.create(input)` | `POST /api/credentials`<br />`settings:admin` |
| Read one masked credential. | `credentials.get(id)` | `GET /api/credentials/:id`<br />`settings:read` |
| Rename, re-scope, or rotate a credential. | `credentials.update(id, input)` | `PATCH /api/credentials/:id`<br />`settings:admin` |
| Remove a credential. | `credentials.remove(id)` | `DELETE /api/credentials/:id`<br />`settings:admin` |
| Check the credential against its provider and record the result. | `credentials.verify(id)` | `POST /api/credentials/:id/verify`<br />`settings:admin` |

{/* api-operations:end */}