Authentication and Security

The API Connector is the transactional core of the system. To guarantee maximum security, we do not rely on a traditional user database at this layer. Instead, we use Google Cloud Identity and Access Management (IAM).

Security Model

All API requests must be authenticated. The service is configured to accept requests only from authorized identities.

There are two main ways to authenticate, depending on how your system integrates:

---

1. ID Token authentication (recommended)

To call API endpoints, include a Google ID Token in the Authorization header.

How to obtain the token

If you are calling the API from another service or script, you can obtain the identity token as follows:

Example request (cURL):

curl -X GET "https://api-connector.gtcmexico.net/health" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)"

Header format

The header must look like this:

Authorization: Bearer <YOUR_GOOGLE_ID_TOKEN>

2. Access for developers and external integrations

If you are an external client that needs to connect your own system to the API Connector, follow this process:

1. Service Account provisioning: We assign a Service Account with limited invocation permissions.

2. JWT generation: Your system must use that account's key file (.json) to generate a Google ID Token before each transaction.

3. Token lifetime: Tokens are valid for up to one hour, so your integration must refresh them automatically.

Authentication status codes

When interacting with the API, you may receive the following identity-related response codes:

Code	Meaning	Common cause
200	OK	Authentication successful.
401	Unauthorized	The token expired or was not included in the header.
403	Forbidden	The token is valid, but the account does not have permission.

Important

Never share Service Account keys or ID Tokens in public repositories. These credentials provide direct access to financial transaction execution (top-ups).