Skip to main content

​
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. 
GET /credentials
Query parameters
ParameterTypeDescription
businessEntityIdintegerFilter by business entity (optional)
extendsstring[]Optional fields to include
Response 
{
  "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. 
GET /credentials/:credentialId
Path parameters
ParameterTypeDescription
credentialIdstringCredential ID
Query parameters
ParameterTypeDescription
includeSecretsbooleanInclude decrypted secure strings (default: false)
includeRegistrationsbooleanInclude linked registrations (default: false)
Response 
{
  "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. 
POST /credentials
Request body 
{
  "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 
{
  "credential": {
    "id": "cred_abc123"
  }
}

​
Update credential

Update an existing credential. 
POST /credentials/:credentialId
Path parameters
ParameterTypeDescription
credentialIdstringCredential ID
Request body 
{
  "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 
{
  "credential": {
    "id": "cred_abc123"
  }
}

​
Delete credential

Remove a credential. 
DELETE /credentials/:credentialId
Path parameters
ParameterTypeDescription
credentialIdstringCredential ID
Response Returns 204 No Content on success.

​
Supported credentials

​
Get supported credential types

Get all credential types available for a country. 
GET /credentials/supportedCredentials
Query parameters
ParameterTypeDescription
countrystringISO 3166-1 alpha-2 country code (optional)
Response 
{
  "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
{
  "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
{
  "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

Associate a credential with a business entity: 
POST /business-entity/:businessEntityId/credentials/:credentialId
This makes the credential accessible when viewing the business entity. Associate a credential with a specific registration: 
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.