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

# Credentials API

> Manage secure login credentials for government portals and systems

## Overview

The Credentials API provides secure storage for login credentials to government portals and systems, including tax filing portals, corporate registries, payroll systems, and banking portals. Credentials can be linked to business entities and registrations, and shared with accountants and service providers.

## Core endpoints

### List credentials

Get all credentials accessible to the user.

```http theme={null}
GET /credentials
```

**Query parameters**

| Parameter          | Type      | Description                          |
| ------------------ | --------- | ------------------------------------ |
| `businessEntityId` | integer   | Filter by business entity (optional) |
| `extends`          | string\[] | Optional fields to include           |

**Response**

```json theme={null}
{
  "credentials": [
    {
      "id": "cred_abc123",
      "name": "IRS e-Services",
      "type": "CORPORATE_TAX_PORTAL",
      "country": "US",
      "jurisdiction": "FEDERAL",
      "url": "https://www.irs.gov/e-services",
      "blocks": [
        {
          "type": "PLAIN_TEXT",
          "label": "Username",
          "value": "john.doe@acme.com"
        },
        {
          "type": "SECURE_STRING",
          "label": "Password",
          "value": "***"
        }
      ],
      "createdAt": "2020-01-15T10:00:00Z",
      "updatedAt": "2024-03-20T15:30:00Z"
    }
  ],
  "count": 1
}
```

### Get credential

Retrieve a single credential by ID.

```http theme={null}
GET /credentials/:credentialId
```

**Path parameters**

| Parameter      | Type   | Description   |
| -------------- | ------ | ------------- |
| `credentialId` | string | Credential ID |

**Query parameters**

| Parameter              | Type    | Description                                       |
| ---------------------- | ------- | ------------------------------------------------- |
| `includeSecrets`       | boolean | Include decrypted secure strings (default: false) |
| `includeRegistrations` | boolean | Include linked registrations (default: false)     |

**Response**

```json theme={null}
{
  "credential": {
    "id": "cred_abc123",
    "name": "IRS e-Services",
    "type": "CORPORATE_TAX_PORTAL",
    "country": "US",
    "jurisdiction": "FEDERAL",
    "url": "https://www.irs.gov/e-services",
    "blocks": [
      {
        "type": "PLAIN_TEXT",
        "label": "Username",
        "value": "john.doe@acme.com"
      },
      {
        "type": "SECURE_STRING",
        "label": "Password",
        "value": "MySecurePassword123!"
      }
    ],
    "registrations": [
      {
        "id": "reg_xyz789",
        "type": "INCOME_TAX"
      }
    ]
  }
}
```

### Create credential

Add a new credential.

```http theme={null}
POST /credentials
```

**Request body**

```json theme={null}
{
  "name": "IRS e-Services",
  "type": "CORPORATE_TAX_PORTAL",
  "country": "US",
  "jurisdiction": "FEDERAL",
  "url": "https://www.irs.gov/e-services",
  "blocks": [
    {
      "type": "PLAIN_TEXT",
      "label": "Username",
      "value": "john.doe@acme.com"
    },
    {
      "type": "SECURE_STRING",
      "label": "Password",
      "value": "MySecurePassword123!"
    },
    {
      "type": "PLAIN_TEXT",
      "label": "Account Number",
      "value": "12-3456789"
    }
  ]
}
```

**Response**

```json theme={null}
{
  "credential": {
    "id": "cred_abc123"
  }
}
```

### Update credential

Update an existing credential.

```http theme={null}
POST /credentials/:credentialId
```

**Path parameters**

| Parameter      | Type   | Description   |
| -------------- | ------ | ------------- |
| `credentialId` | string | Credential ID |

**Request body**

```json theme={null}
{
  "name": "IRS e-Services (Updated)",
  "url": "https://www.irs.gov/e-services-new",
  "blocks": [
    {
      "type": "PLAIN_TEXT",
      "label": "Username",
      "value": "jane.smith@acme.com"
    },
    {
      "type": "SECURE_STRING",
      "label": "Password",
      "value": "NewPassword456!"
    }
  ]
}
```

**Response**

```json theme={null}
{
  "credential": {
    "id": "cred_abc123"
  }
}
```

### Delete credential

Remove a credential.

```http theme={null}
DELETE /credentials/:credentialId
```

**Path parameters**

| Parameter      | Type   | Description   |
| -------------- | ------ | ------------- |
| `credentialId` | string | Credential ID |

**Response**

Returns `204 No Content` on success.

## Supported credentials

### Get supported credential types

Get all credential types available for a country.

```http theme={null}
GET /credentials/supportedCredentials
```

**Query parameters**

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| `country` | string | ISO 3166-1 alpha-2 country code (optional) |

**Response**

```json theme={null}
{
  "supportedCredentials": [
    {
      "type": "CORPORATE_TAX_PORTAL",
      "displayName": "Corporate Tax Portal",
      "description": "Federal corporate income tax filing system",
      "country": "US",
      "jurisdiction": "FEDERAL",
      "url": "https://www.irs.gov/e-services",
      "blocks": [
        {
          "type": "PLAIN_TEXT",
          "label": "Username",
          "required": true
        },
        {
          "type": "SECURE_STRING",
          "label": "Password",
          "required": true
        }
      ]
    }
  ],
  "count": 1
}
```

## Credential types

### Corporate tax portals

Federal/national income tax filing systems:

* **US**: IRS e-Services, state tax portals
* **UK**: HMRC online services
* **India**: Income Tax e-Filing portal
* **Canada**: CRA My Business Account
* **Singapore**: myTax Portal

### Indirect tax portals

VAT/GST/sales tax filing systems:

* **US**: State sales tax portals
* **UK**: HMRC VAT online
* **India**: GST portal
* **Singapore**: myTax GST
* **UAE**: Federal Tax Authority portal

### Payroll tax portals

Withholding and unemployment insurance systems:

* **US**: State withholding portals, SUTA portals
* **UK**: HMRC PAYE online
* **India**: ESIC, EPFO portals
* **Singapore**: CPF portal

### Company secretarial portals

Business registry filing systems:

* **US**: State Secretary of State portals
* **UK**: Companies House WebFiling
* **India**: MCA portal
* **Singapore**: BizFile+

### Social security portals

Employee benefit systems:

* **US**: Social Security Business Services Online
* **India**: ESIC, EPFO
* **Singapore**: CPF Board

### Banking portals

Financial institution access:

* Bank online banking
* Payment processing portals
* Treasury management systems

## Credential blocks

Credentials consist of flexible blocks that can store different types of information:

### Plain text blocks

Store non-sensitive information:

* Usernames
* Account numbers
* Email addresses
* User IDs
* Reference numbers

```json theme={null}
{
  "type": "PLAIN_TEXT",
  "label": "Username",
  "value": "john.doe@acme.com"
}
```

### Secure string blocks

Store sensitive information (encrypted at rest):

* Passwords
* PINs
* Access tokens
* API keys
* Security answers

```json theme={null}
{
  "type": "SECURE_STRING",
  "label": "Password",
  "value": "MySecurePassword123!"
}
```

### Custom blocks

Add jurisdiction-specific fields as needed. The block structure is flexible to accommodate any credential format.

## Linking credentials

### Link to business entity

Associate a credential with a business entity:

```http theme={null}
POST /business-entity/:businessEntityId/credentials/:credentialId
```

This makes the credential accessible when viewing the business entity.

### Link to registration

Associate a credential with a specific registration:

```http theme={null}
POST /business-entity/:businessEntityId/registrations/:registrationId/credential/:credentialId
```

This links the credential to a specific government registration, enabling automated filing workflows.

## Security

* **Encryption**: Secure string blocks are encrypted at rest using industry-standard encryption
* **Access control**: Credentials are only accessible to authorized users
* **Audit logging**: All credential access and modifications are logged
* **Sharing**: Credentials can be shared with accountants and service providers

## Sharing with accountants

Credentials can be shared with external accountants and service providers who need portal access for filing and compliance work. The sharing mechanism ensures proper authorization and audit trails.

## Related resources

* [Business Entity API](/engine/commendaos/business-entity) - Link credentials to entities
* [Registrations API](/engine/commendaos/registrations) - Link credentials to registrations