ESEN

API keys

An API key belongs to a person (any individual or legal entity registered in your tenant) and authenticates your requests to Fiscalapi on their behalf, so each request has that person's roles and permissions. Use these endpoints to create, retrieve, update, and delete the API keys in your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data).

Other people's API keys

Each API key belongs to a person. The tenant owner (the person who created the tenant) manages the API keys of every person in the tenant; everyone else manages only their own. For anyone who isn't the owner, the endpoints respond as follows:

EndpointResponse for anyone who isn't the owner
List API keysReturns only their own API keys.
Create an API keyReturns 403 if the personId belongs to another person.
Get, update, or deleteReturns 404 for another person's API key, the same as for an API key that doesn't exist.

API key model

The API key model represents a person's authentication key.

Properties

  • Name
    id
    Type
    string?
    Description

    The API key's unique identifier, assigned by Fiscalapi.

  • Name
    environment
    Type
    string?
    Description

    The environment the API key belongs to.

  • Name
    apiKeyValue
    Type
    string?
    Description

    The API key value you authenticate your requests with.

  • Name
    personId
    Type
    string?
    Description

    The ID of the person the API key belongs to.

  • Name
    tenantId
    Type
    string?
    Description

    The ID of the tenant the API key belongs to.

  • Name
    apiKeyStatus
    Type
    string?
    Description

    The API key's status.

    Type
    enum:
    Values
    01
  • Name
    description
    Type
    string?
    Description

    The API key's name or description.

GET/api/v4/apikeys

List API keys

This endpoint returns a paginated list of API keys, ten per page by default. Set the page and its size with the query parameters. The tenant owner receives every API key in the tenant, and everyone else receives only their own (see Other people's API keys).

Query parameters

  • Name
    pageNumber
    Type
    int
    required
    Description

    The page number you want to retrieve.

    Default:
    1
  • Name
    pageSize
    Type
    int
    required
    Description

    The number of API keys per page, from 1 to 10.

    Default:
    10

Request

GET
/api/v4/apikeys?pageNumber=1&pageSize=2
curl --location 'https://test.fiscalapi.com/api/v4/apikeys?pageNumber=1&pageSize=2' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

{
    "data": {
        "items": [
            {
                "environment": "Test",
                "apiKeyValue": "sk_test_...",
                "personId": "5fd9f48c-a6a2-474f-944b-88a01751d432",
                "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
                "apiKeyStatus": 0,
                "description": null,
                "id": "539d247f-6624-4086-86fc-170715af9fbd",
                "createdAt": "2025-01-07T15:24:22.1446925",
                "updatedAt": "2025-01-07T15:24:45.7387097"
            },
            {
                "environment": "Test",
                "apiKeyValue": "sk_test_...",
                "personId": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
                "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
                "apiKeyStatus": 1,
                "description": null,
                "id": "99553e5f-7562-40e7-8b0b-7eb3548b77f0",
                "createdAt": "2025-01-07T15:28:37.5030339",
                "updatedAt": "2025-01-07T15:28:37.5030361"
            }
        ],
        "pageNumber": 1,
        "totalPages": 3,
        "totalCount": 6,
        "hasPreviousPage": false,
        "hasNextPage": true
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}
POST/api/v4/apikeys

Create an API key

This endpoint creates an API key for a person in your tenant. Only the tenant owner can create API keys for another person; everyone else can create them only for themselves (see Other people's API keys).

Request body

  • Name
    personId
    Type
    string?
    Description

    The ID of the person the new API key belongs to.

  • Name
    description
    Type
    string??
    Description

    The API key's name or description.

Errors

The message arrives in the details field of the response model.

StatusWhen it happensMessage
403You send another person's personId and you aren't the tenant owner.Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.

Request

POST
/api/v4/apikeys
curl --location 'https://test.fiscalapi.com/api/v4/apikeys' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data '{
  "personId" : "<person_id>",
  "description" : "api-key para cliente ABC"
}'

Response

{
    "data": {
        "environment": "Test",
        "apiKeyValue": "sk_test_...",
        "personId": "5fd9f48c-a6a2-474f-944b-88a01751d432",
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "apiKeyStatus": 1,
        "description": "api-key para cliente ABC",
        "id": "6c757df8-9f22-42b9-890d-3ae08c143355",
        "createdAt": "2025-05-01T08:32:15.2863188",
        "updatedAt": "2025-05-01T08:32:15.2863194"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}
GET/api/v4/apikeys/<id>

Get an API key by ID

This endpoint retrieves an API key by its ID. If the API key belongs to another person and you aren't the tenant owner, it returns 404, the same as for an API key that doesn't exist (see Other people's API keys).

Errors

In the message, <id> is the ID of the API key.

StatusWhen it happensMessage
404The API key doesn't exist, or it belongs to another person and you aren't the tenant owner.No such resource for the given Id: <id>

Request

GET
/api/v4/apikeys/<id>
curl --location 'https://test.fiscalapi.com/api/v4/apikeys/99553e5f-7562-40e7-8b0b-7eb3548b77f0' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

{
    "data": {
        "environment": "Test",
        "apiKeyValue": "sk_test_...",
        "personId": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "apiKeyStatus": 1,
        "description": "api-key del cliente ABC",
        "id": "0153a9b8-f219-46ba-a7b5-f4ec92bdfa26",
        "createdAt": "2025-01-07T15:28:37.5030339",
        "updatedAt": "2025-01-07T15:28:37.5030361"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}
PUT/api/v4/apikeys/<id>

Update an API key

This endpoint updates the name or status of an API key in your tenant. If the API key belongs to another person and you aren't the tenant owner, it returns 404, the same as for an API key that doesn't exist (see Other people's API keys).

Request body

  • Name
    id
    Type
    string?
    Description

    The ID of the API key you want to update.

  • Name
    description
    Type
    string?
    Description

    The API key's name or description.

  • Name
    apiKeyStatus
    Type
    string?
    Description

    The API key's status.

    Type
    enum:
    Values
    01

Errors

In the message, <id> is the ID of the API key.

StatusWhen it happensMessage
404The API key doesn't exist, or it belongs to another person and you aren't the tenant owner.No such resource for the given Id: <id>

Request

PUT
/api/v4/apikeys/<id>
curl --location --request PUT 'https://test.fiscalapi.com/api/v4/apikeys/<id>' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data '{
  "id": "6c757df8-9f22-42b9-890d-3ae08c143355",
  "description": "Api-key server 001...",
  "apiKeyStatus": 0
}'

Response

{
    "data": {
        "environment": "Test",
        "apiKeyValue": "sk_test...",
        "personId": "5fd9f48c-a6a2-474f-944b-88a01751d432",
        "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
        "apiKeyStatus": 0,
        "description": "Api-key server 001",
        "id": "6c757df8-9f22-42b9-890d-3ae08c143355",
        "createdAt": "2025-05-01T08:32:15.2863188",
        "updatedAt": "2025-05-01T08:33:09.0203389"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}
DELETE/api/v4/apikeys/<id>

Delete an API key

This endpoint deletes an API key from your tenant. If the API key belongs to another person and you aren't the tenant owner, it returns 404 and doesn't delete it (see Other people's API keys).

When you delete a person with Delete an issuer, Fiscalapi revokes their API keys the same way this endpoint does: they no longer appear in the list, and Get an API key by ID returns 404.

Errors

In the message, <id> is the ID of the API key.

StatusWhen it happensMessage
404The API key doesn't exist, or it belongs to another person and you aren't the tenant owner.No such resource for the given Id: <id>

Request

DELETE
/api/v4/apikeys/<id>
curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/apikeys/<id>' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

Was this page helpful?