Authentication

How to send

Every call requires two mandatory headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Example of an authenticated call to query the balance:

curl https://api.magen.processamento.com/v1/user/balance \
  -H "Authorization: Bearer $MAGEN_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://api.magen.processamento.com/v1/user/balance', {
  headers: {
    Authorization: `Bearer ${process.env.MAGEN_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const balance = await res.json();

import os
import requests

res = requests.get(
    'https://api.magen.processamento.com/v1/user/balance',
    headers={
        'Authorization': f'Bearer {os.environ["MAGEN_TOKEN"]}',
        'Content-Type': 'application/json',
    },
)
balance = res.json()

req, _ := http.NewRequest("GET", "https://api.magen.processamento.com/v1/user/balance", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("MAGEN_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.magen.processamento.com/v1/user/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('MAGEN_TOKEN'),
    'Content-Type: application/json',
  ],
]);
$balance = json_decode(curl_exec($ch), true);

Where to store

Never expose the token on the front-end, in a public repository, or in logs. Treat it as a password: store it in a vault and inject it via environment variable.

Recommendations:

Google Secret Manager, ideal if you already use GCP.
HashiCorp Vault, for self-hosted setups.
AWS Secrets Manager, the AWS equivalent.
Environment variable in CI, never commit it.

Error format

Every error response from Magen (4xx and 5xx) follows the same format. The most important field is requestId, which uniquely identifies the call in Magen's internal logs.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Não foi possível processar esta solicitação",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}

Field	Purpose
`statusCode`	HTTP response code (mirrors the status).
`error`	Short name of the error (`Unauthorized`, `Bad Request`, `Internal Server Error`).
`message`	Description in PT of what happened. Use in logs, not for end users.
`requestId`	Unique ID of the call at Magen. Send this ID when opening a support ticket, they trace it directly.

Always log the requestId in your errors. When opening support with "got an error in production", the team asks for this ID first. Those who have the requestId get investigation in minutes; those who don't, take hours.

try {
  const res = await fetch(url, { headers, body });
  if (!res.ok) {
    const err = await res.json();
    log.error('Magen error', {
      requestId: err.requestId,
      statusCode: err.statusCode,
      message: err.message,
      endpoint: url,
    });
    throw new Error(`Magen ${err.statusCode}: ${err.message} (requestId=${err.requestId})`);
  }
} catch (e) {
  // ...
}

Opening support with the requestId

Open ticket Knowledge base Support portal

Resolving errors

401 Unauthorized

The most common causes, in order:

Missing token, the Authorization header was not sent.
Incorrect token, typo, extra whitespace, wrong encoding.
Revoked token, it was rotated and you are using the old one.
Insufficient permission, the token does not have the endpoint's scope.

Example response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmou00000abcdef01s6ghij1k2lm"
}

403 Forbidden

The token is valid but does not have permission for the operation. Check whether the endpoint requires an additional scope or whether your account is enabled for the resource (for example, internal transfer may require prior approval).

Rotation

If the token leaks, contact Magen support immediately to issue a new token and revoke the previous one.

Authentication

On this page