Credentials

The API uses two kinds of credentials associated with an entity (RFC):

CIEC and CSD serve different purposes. You need a CIEC to pull SAT data and a CSD to stamp or cancel invoices. Both are stored on the entity record, but via different endpoints.

CIEC — entity registration and management

The CIEC password is stored when you create an entity and updated via PATCH. The SAT validates it asynchronously; poll credential_status until it settles.

Create an entity (registers the CIEC)

POST /v1/entities

{
  "tax_id":        "XEXX010101000",
  "name":          "MI EMPRESA SA DE CV",
  "ciec_password": "Pass1234"
}

Request fields

Response — 201 Created

{
  "id":                "9b1c0e2a-4d3f-4a1b-8c2d-1e2f3a4b5c6d",
  "name":              "MI EMPRESA SA DE CV",
  "tax_id":            "XEXX010101000",
  "credential_status": "pending"
}

Response fields

Update an entity (rotates the CIEC)

PATCH /v1/entities/{id}

Send only the fields to update. Changing ciec_password resets credential_status to pending and triggers re-validation automatically.

{ "ciec_password": "NewPass1" }

Request fields

List entities

GET /v1/entities

Returns all entities belonging to the authenticated organization. Each item has the same shape as the create response.

Get an entity

GET /v1/entities/{id}

Returns a single entity by UUID. Returns 404 if not found or not in your organization.

Delete an entity

DELETE /v1/entities/{id} — permanently removes the entity and its related data. Returns 204 No Content.

CIEC status (credential_status)

CIEC is only for extractions. Invoicing does not use the CIEC. To issue or cancel CFDI you need a CSD (see below).

CSD — certificate management for invoicing

A CSD (Certificado de Sello Digital) is a digital seal certificate issued by the SAT. It consists of two files — a .cer (public certificate) and a .key (encrypted private key). You upload them together with the key password. The private key is encrypted at rest and never returned through the API.

Every entity that issues invoices must have exactly one active CSD at a time. Uploading a new CSD automatically deactivates any existing active CSD for that entity.

Upload a CSD

POST /v1/entities/{entity_id}/credentials

Send the .cer and .key file contents base64-encoded with the key password:

{
  "cer":      "<base64-encoded .cer bytes>",
  "key":      "<base64-encoded .key bytes>",
  "password": "your_key_password"
}

Request fields

Validation performed before storing:

• The .cer and .key must be a matching pair (the private key must belong to the certificate).
• The RFC in the certificate must match the entity's tax_id.
• The certificate must be a CSD (not a FIEL/e.firma).
• The certificate must not be expired.

Response — 201 Created

{
  "id":            "01936a7b-4c2d-7e8f-9a0b-1c2d3e4f5a6b",
  "kind":          "csd",
  "status":        "active",
  "is_active":     true,
  "serial_number": "30001000000500003416",
  "valid_from":    "2023-01-10T06:00:00+00:00",
  "valid_to":      "2027-01-10T06:00:00+00:00",
  "created_at":    "2026-07-01T12:00:00+00:00"
}

Response fields

Upload errors

Every non-2xx response carries a stable reason:

List credentials

GET /v1/entities/{entity_id}/credentials

Returns all CSD credentials stored for the entity, newest first. Each item has the same shape as the upload response.

[
  {
    "id":            "01936a7b-4c2d-7e8f-9a0b-1c2d3e4f5a6b",
    "kind":          "csd",
    "status":        "active",
    "is_active":     true,
    "serial_number": "30001000000500003416",
    "valid_from":    "2023-01-10T06:00:00+00:00",
    "valid_to":      "2027-01-10T06:00:00+00:00",
    "created_at":    "2026-07-01T12:00:00+00:00"
  }
]

Activate or deactivate a credential

PATCH /v1/entities/{entity_id}/credentials/{id}

{ "is_active": true }

When activating a credential, all other credentials of the same kind on the entity are deactivated first so the one-active-per-kind invariant is always maintained.

Returns the updated credential resource (200 OK).

Delete a credential

DELETE /v1/entities/{entity_id}/credentials/{id}

Removes the credential record and attempts to delete the associated stored files. File deletion failures are silently ignored; the record is always removed. Returns 204 No Content.

Which credential does each feature need?

Keeping credentials current

CIEC: the SAT does not expire CIEC passwords on a fixed schedule, but users may change them at any time. If extractions start failing with invalid status, update the password via PATCH.

CSD: the SAT issues CSDs with a validity of up to 4 years. Check valid_to and re-upload before the certificate expires to avoid stamping failures. Upload the new CSD — it will become active automatically and deactivate the old one.