Fincore · API reference · Authentication

Create authentication token

POST /v1/clients/{clientId}/auth/credential-tokens

Base URL https://apicore.stg.finch.lat · operationId createCredentialToken

Exchanges a client_secret for a JWT bearer token. Use the returned token in the Authorization: Bearer <token> header for authenticated Fincore endpoints. Tokens expire; create a new token after receiving 401 Unauthorized.

Authorization

ApiKeyAuth API key in header x-api-key

API key sent in the x-api-key header. Create credentials from the Authentication guide before using protected endpoints.

Path parameters

clientId string (uuid) required

Unique identifier for the client.

Request body application/json · required

client_id string required

Client UUID associated with the credential.

client_secret string required

Client secret returned by the credential bootstrap endpoint.

Responses

200 Successfully created credential token. application/json

id string (uuid) required

Unique identifier of the generated credential token.

client_id string (uuid) required

Client UUID associated with the token.

client_credential_id string (uuid) required

Client credential UUID used to create the token.

token string required

JWT authentication token

status string required

Token lifecycle status.

ACTIVE INACTIVE

expires_at string required

Mexico City local time (UTC-6) when the token expires. Unlike the audit timestamps in this response, this value is returned without a UTC offset. Interpret it as UTC-6; do not treat it as UTC.

created_at string (date-time) required

Mexico City local time (UTC-6) when the token was created, including the -06:00 offset.

updated_at string (date-time) required

Mexico City local time (UTC-6) when the token was last updated, including the -06:00 offset.

deleted_at string | null required

Timestamp when the token was deleted, or null if active.

400 Token creation request is invalid. Possible causes: malformed clientId, missing client_id, missing client_secret, or client_id not matching the path client. It also fails when the credential is inactive, deleted, or not valid for the target environment. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

401 Authentication failed. Possible causes: missing x-api-key, invalid API key, invalid client secret, or credentials that do not belong to the requested client. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

500 Unexpected server error. See Error catalog before retrying non-idempotent operations. application/json

code integer required

gRPC status code mapped to HTTP.

message string required

General error message.

details array of ErrorDetail required

Detailed error causes returned by the service.

reason details[].reason string required

Machine-readable error category.

DATA_ERROR FAILED_PRECONDITION MISSING_REQUIRED_FIELDS RESOURCE_NOT_FOUND UNAUTHORIZED PERMISSION_DENIED UNIQUE_VIOLATION INTERNAL

domain details[].domain string required

Service domain that produced the error.

metadata details[].metadata object required

Additional error metadata, including the detailed message and HTTP code.

error_detail details[].metadata.error_detail string

Human-readable detail returned by the service.

http_code details[].metadata.http_code string

HTTP status code associated with this error.

error_code details[].metadata.error_code string

Optional internal error catalog code when available.

This request is in the Monato · Fincore Postman collection, folder Authentication.Download collection

Request

curl -X POST "https://apicore.stg.finch.lat/v1/clients/{clientId}/auth/credential-tokens" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_secret": "your_client_secret_here"
}'

const body = JSON.stringify({
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_secret": "your_client_secret_here"
});

const res = await fetch("https://apicore.stg.finch.lat/v1/clients/{clientId}/auth/credential-tokens", {
  method: "POST",
  headers: {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

payload = {
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_secret": "your_client_secret_here"
}

res = requests.post(
    "https://apicore.stg.finch.lat/v1/clients/{clientId}/auth/credential-tokens",
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

Response

{
  "id": "1307f4e3-3960-4b98-9a14-0b6839245cc9",
  "client_id": "c2d1d1e3-3340-4170-980e-e9269bbbc551",
  "client_credential_id": "e981c6d8-4d49-45f2-a7ee-f956dca15500",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJjMmQxZDFlMy0zMzQwLTQxNzAtOTgwZS1lOTI2OWJiYmM1NTEiLCJleHAiOjE3NDEyODE0MTl9.ziSqMClLqwUVfyM15bqUF_7-PINY0ZiWkH01s8pO3gA",
  "status": "ACTIVE",
  "expires_at": "2025-03-06 11:16:59.491631",
  "created_at": "2025-03-05 11:16:59.488685-06:00",
  "updated_at": "2025-03-05 11:16:59.488685-06:00",
  "deleted_at": null
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}