Credentials API - Commenda — Entity Management, Indirect Tax, Compliance & Corporate APIs for Multinationals

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 the credentials shared with a business entity.

GET /credentials?businessEntityId=:businessEntityId

Query parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity whose credentials to list (required)
`extends`	string[]	Optional fields to include: `REGISTRATIONS` fills in `isUsed`, whether the credential is active and linked to a registration

A credential appears here once it has been linked to the business entity. Secure string values are never returned by this endpoint; use Get credential with includeSecrets=true to read them. Response

{
  "credentials": [
    {
      "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23",
      "internalIdentifier": "US_IRS_E_SERVICES",
      "name": "IRS e-Services",
      "credentialType": "CORPORATE_TAX",
      "country": "US",
      "jurisdiction": null,
      "portalURL": "https://www.irs.gov/e-services",
      "notes": null,
      "isCustom": false,
      "status": "ACTIVE",
      "blocks": [
        {
          "id": "cm3j8k9l00005l508a1b2c3d4",
          "key": "User name",
          "type": "PlainText",
          "value": "john.doe@acme.com",
          "secretMask": null,
          "isCustomBlock": false
        },
        {
          "id": "cm3j8k9l00006l508e5f6g7h8",
          "key": "Password",
          "type": "SecureString",
          "value": null,
          "secretMask": "3!",
          "isCustomBlock": false
        }
      ],
      "isUsed": null,
      "createdAt": 1579082400000,
      "updatedAt": 1710948600000,
      "lastUpdateAt": 1710948600000
    }
  ],
  "count": 1
}

createdAt, updatedAt and lastUpdateAt are Unix timestamps in milliseconds.

Get credential

Retrieve a single credential by ID.

GET /credentials/:credentialId

Path parameters

Parameter	Type	Description
`credentialId`	string	Credential ID

Query parameters

Parameter	Type	Description
`includeSecrets`	boolean	Pass `true` to include decrypted secure string values. Omit it to leave them out.
`includeRegistrations`	boolean	Pass `true` to include the registrations the credential is linked to. Omit it to leave them out.

Response The credential has the same shape as an entry of List credentials, without isUsed; the example below is trimmed. registrations is null unless you pass includeRegistrations=true.

{
  "credential": {
    "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23",
    "internalIdentifier": "US_IRS_E_SERVICES",
    "name": "IRS e-Services",
    "credentialType": "CORPORATE_TAX",
    "country": "US",
    "jurisdiction": null,
    "portalURL": "https://www.irs.gov/e-services",
    "blocks": [
      {
        "id": "cm3j8k9l00005l508a1b2c3d4",
        "key": "User name",
        "type": "PlainText",
        "value": "john.doe@acme.com",
        "secretMask": null,
        "isCustomBlock": false
      },
      {
        "id": "cm3j8k9l00006l508e5f6g7h8",
        "key": "Password",
        "type": "SecureString",
        "value": "MySecurePassword123!",
        "secretMask": "3!",
        "isCustomBlock": false
      }
    ],
    "registrations": [
      {
        "registrationId": "cm3h4d5e60003l508p2q4r6st",
        "registrationIdentifier": "REG:US:EIN_APPLICATION",
        "registrationName": ""
      }
    ]
  }
}

Create credential

Add a new credential. Either name a credential from the country’s supported credentials with internalIdentifier, or describe a custom one with name and country.

POST /credentials

Request body

{
  "internalIdentifier": "US_IRS_E_SERVICES",
  "credentialType": "CORPORATE_TAX",
  "portalURL": "https://www.irs.gov/e-services",
  "blocks": [
    {
      "key": "User name",
      "type": "PlainText",
      "value": "john.doe@acme.com"
    },
    {
      "key": "Password",
      "type": "SecureString",
      "value": "MySecurePassword123!"
    }
  ]
}

Field	Type	Required	Description
`internalIdentifier`	string	Unless custom	The `internalIdentifier` of a supported credential. Cannot be combined with `name`.
`name`	string	Custom only	Name of a custom credential
`country`	string	Custom only	Country of a custom credential (ISO 3166-1 alpha-2). A supported credential takes its country from the catalog.
`credentialType`	string	Yes	One of the credential types
`jurisdiction`	string	No	Jurisdiction the credential applies to. Required for supported credentials that are jurisdiction-specific.
`portalURL`	string	No	Login URL of the portal
`notes`	string	No	Free-text notes
`blocks`	object[]	Yes	The credential’s blocks. For a supported credential, each block’s `key` and `type` must match a block of that credential, unless `isCustomBlock` is `true`.

Response Returns 201 Created.

{
  "credential": {
    "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23"
  }
}

Update credential

Update an existing credential.

POST /credentials/:credentialId

Path parameters

Parameter	Type	Description
`credentialId`	string	Credential ID

Request body Blocks are updated by id. blocks is required; send an empty array to change only other fields.

{
  "name": "IRS e-Services (Updated)",
  "blocks": [
    {
      "id": "cm3j8k9l00005l508a1b2c3d4",
      "value": "jane.smith@acme.com"
    },
    {
      "id": "cm3j8k9l00006l508e5f6g7h8",
      "value": "NewPassword456!"
    }
  ]
}

Field	Type	Required	Description
`blocks`	object[]	Yes	Blocks to change: each takes the block’s `id`, and a new `key` and/or `value`
`blocksToDelete`	string[]	No	IDs of blocks to remove
`name`	string	No	New name
`portalURL`	string	No	New login URL
`notes`	string	No	New notes

A block ID that does not belong to the credential returns 400 Bad Request. Response Returns 200 OK.

{
  "credential": {
    "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23"
  }
}

Delete credential

Remove a credential.

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 the credentials Commenda supports for a country.

GET /credentials/supportedCredentials?country=:country

Query parameters

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

Response Each entry describes one block of a supported credential, so a credential with a user name and a password appears twice under the same internalIdentifier. count is the number of entries.

{
  "supportedCredentials": [
    {
      "internalIdentifier": "US_IRS_E_SERVICES",
      "name": "IRS e-Services",
      "credentialType": "CORPORATE_TAX",
      "country": "US",
      "jurisdiction": null,
      "portalURL": "https://www.irs.gov/e-services",
      "blockName": "User name",
      "blockType": "PlainText"
    },
    {
      "internalIdentifier": "US_IRS_E_SERVICES",
      "name": "IRS e-Services",
      "credentialType": "CORPORATE_TAX",
      "country": "US",
      "jurisdiction": null,
      "portalURL": "https://www.irs.gov/e-services",
      "blockName": "Password",
      "blockType": "SecureString"
    }
  ],
  "count": 2
}

Credential types

The credentialType field takes one of CORPORATE_TAX, INDIRECT_TAX, PAYROLL_TAX, COMPANY_SECRETARIAL, SOCIAL_SECURITY, BANKING or OTHER.

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+

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. Each block has a key (its label), a type and a value:

Plain text blocks

Store non-sensitive information:

Usernames
Account numbers
Email addresses
User IDs
Reference numbers

{
  "key": "User name",
  "type": "PlainText",
  "value": "john.doe@acme.com"
}

Secure string blocks

Store sensitive information (encrypted at rest):

Passwords
PINs
Access tokens
API keys
Security answers

{
  "key": "Password",
  "type": "SecureString",
  "value": "MySecurePassword123!"
}

Responses show the last two characters of a secure string as secretMask, and return its value only when you get the credential with includeSecrets=true.

Custom blocks

Add jurisdiction-specific fields as needed by setting isCustomBlock: true on the block. A custom block does not have to match a block of the supported credential, so the block structure can accommodate any credential format.

Linking credentials

Link to business entity

Associate a credential with a business entity:

POST /business-entities/:businessEntityId/credentials/:credentialId

This makes the credential accessible when viewing the business entity, and lists it under List credentials for that entity. Returns 200 OK:

{
  "credential": {
    "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23"
  }
}

Link to registration

Associate a credential with a specific registration:

POST /business-entities/:businessEntityId/registrations/:registrationId/credential/:credentialId

This links the credential to a specific government registration, enabling automated filing workflows. Returns 200 OK with the same body as above.

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

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.

Business Entity API - Link credentials to entities
Registrations API - Link credentials to registrations

​Overview

​Core endpoints

​List credentials

​Get credential

​Create credential

​Update credential

​Delete credential

​Supported credentials

​Get supported credential types

​Credential types

​Corporate tax portals

​Indirect tax portals

​Payroll tax portals

​Company secretarial portals

​Social security portals

​Banking portals

​Credential blocks

​Plain text blocks

​Secure string blocks

​Custom blocks

​Linking credentials

​Link to business entity

​Link to registration

​Security

​Sharing with accountants

​Related resources

Overview

Core endpoints

List credentials

Get credential

Create credential

Update credential

Delete credential

Supported credentials

Get supported credential types

Credential types

Corporate tax portals

Indirect tax portals

Payroll tax portals

Company secretarial portals

Social security portals

Banking portals

Credential blocks

Plain text blocks

Secure string blocks

Custom blocks

Linking credentials

Link to business entity

Link to registration

Security

Sharing with accountants

Related resources