Cobre's Authentication API enables secure, frictionless access to the Cobre Move Money platform. Authenticate with a user_id and secret obtained from the Cobre Portal to receive a short-lived JSON Web Token (JWT) for all subsequent API calls.

Cobre Authentication API Guide

The Cobre Authentication API facilitates secure interactions within the Cobre Money Movement platform. Follow this step-by-step guide to authenticate and use the platform services effectively.

Obtain API Credentials

Before you can authenticate, you need to obtain the necessary API credentials: a user_id and a secret. These credentials are provided within the Cobre ecosystem, ensuring a secure and straightforward way to access the platform.

Authenticate into the Platform

With your API credentials in hand, use them to authenticate into the platform. Send a request to the Authentication API endpoint, including your user_id and secret. Upon successful authentication, the API returns a JSON Web Token (JWT).

Authentication request example:

POST /auth
Content-Type: application/json

{
  "user_id": "your_user_id",
  "secret": "your_secret"
}

Authentication response example:

{
    "access_token": "eyJhbGciOiJSUzI1...",
    "type": "Bearer",
    "expiration_time": 1200
}

Start moving money!

With the JWT token in hand, you will be able to initiate all your money movement operations!

Cobre caches login tokens server-side. When you call the Authentication endpoint with the same credentials, Cobre checks the cache before issuing a new token:

Cache hit — returns the cached token; no new JWT is generated.

Cache miss — generates a new token and stores it in the cache.

The cache TTL is 90% of the token lifetime. This creates a 10% safety buffer where the JWT is still valid but the cache has already expired, so the next login call always fetches a fresh token rather than serving one close to expiry.

Production token lifetime is currently 1 200 s (20 min). This value may change; all proportions below hold for any expiration_time.

What `expiration_time` means in each scenario

Scenario	`expiration_time` in the response
Cache miss (first call, or after cache TTL expires)	Full token lifetime (e.g. 1 200 s)
Cache hit (0 < T < cache TTL)	Remaining cache TTL — not the remaining JWT lifetime

On a cache hit, treat expiration_time as the remaining time until you should refresh — not as the JWT's absolute expiry. Example: at T + 1 min, you may receive 1 020 s even though the underlying JWT was issued earlier.

Parameter	Value (20-min token example)
Token lifetime	1 200 s (20 min)
Cache TTL (90%)	1 080 s (18 min)
10% safety buffer	120 s (2 min) — token valid, cache gone
Recommended client refresh (95%)	1 140 s (19 min)

Token management best practices

Cobre APIs use short-lived access tokens, so your integration must handle token refresh in a controlled way:

Do not request a new token on every API call. This is inefficient and may cause you to be blocked due to rate limiting.

Cache the token, reuse it, and refresh it only when it is close to expiration.

Implement a single token manager that all Cobre API requests share.

This provides:

Lower latency (fewer auth calls)

More stable throughput

Cleaner error handling and observability

Better resilience under load

Recommendations

Cache the token client-side and reuse it until expiration_time elapses — never call /v1/auth on every request.

Refresh at 95% of expiration_time (1 140 s / 19 min for 20-min tokens). The server cache expires at 90% (18 min), so calling at 95% always falls after the cache has already expired — guaranteeing a fresh token.

Share one token per credential set across workers — parallel calls benefit from the same cache entry.

Store tokens in memory when possible (fastest). If you run multiple instances, consider a shared cache (Redis, Memcached) so all replicas reuse the same token.

Reference implementation (language-agnostic pseudocode)

Use this logic before every request to Cobre:

function getValidToken():
  refresh_at = cached_expires_at - (0.05 * cached_expiration_time)

  if cached_token exists AND now < refresh_at:
      return cached_token

  lock(token_refresh_lock):
      # Double-check after acquiring lock
      if cached_token exists AND now < refresh_at:
          return cached_token

      response = requestNewToken()
      cached_token = response.access_token
      cached_expiration_time = response.expiration_time
      cached_expires_at = now + response.expiration_time
      return cached_token

If your system makes parallel requests, use a lock or mutex to ensure only one refresh occurs at a time and all other requests wait for it. This avoids token storms — multiple simultaneous token refreshes under load.

Handling a 401 response

A 401 on any Cobre API endpoint means the Authorization: Bearer <access_token> header is missing, malformed, or the token has expired or is otherwise no longer valid — distinct from 403 (valid token, insufficient permission on that resource).

A 401 should be rare if you follow the refresh-at-95% pattern above. Treat it as a fallback safety net, not your primary token-management strategy.

Recommended handling:

On 401, call POST /auth again with your user_id/secret to obtain a new token.

Retry the original request once with the new token.

If the retry also returns 401, stop retrying — this signals invalid credentials (not an expired token) and should surface as a hard failure for someone to check the user_id/secret.

For non-idempotent requests (e.g. creating a Money Movement), do not retry-after-refresh without an idempotency key. If the original request was already processed by Cobre before the response reached you, a blind retry can create a duplicate. Reuse the same idempotency key on the retry.

response = call(endpoint, token)
if response.status == 401:
    token = requestNewToken()
    response = call(endpoint, token, idempotency_key=same_key)
    if response.status == 401:
        raise AuthenticationError("Invalid credentials")

Allowed Actions on Authentication

🔑 Authenticate

Description: Exchange your user_id and secret for a short-lived Bearer token.

What to expect after the action: A JWT with access_token, type, and expiration_time.

📘 Learn more:

🔗 Authentication

How to Get Started

Before you begin, we recommend having clarity on the preliminary steps required before using this solution.

Create your API credentials from the Portal

Access the Portal and find the Developers section at the bottom of the left side menu.

Once in the Developers section, click on the API credentials tab, then in + Create Credential.

A new window will pop-up. Assign an alias and select the role to create your API credential with the necessary access.

Once the credential is generated, make sure you store it in a safe place since it won't be possible to get it again.

What to expect after using this API

Use the JWT on all Cobre API calls

Pass the token in the Authorization: Bearer <access_token> header on every subsequent request to Cobre APIs.

Cache and refresh based on expiration_time

Store the token and its expiration timestamp. Reuse the cached token until you reach the 95% refresh point described in Token management best practices — do not request a new token on every business API call.

Continue to other API Guides

See next sections to learn more about Cobre APIs and start integrating money movement flows.

Get to know our Authentication API technical documentation:

Authentication API

Get Authentication tokens to start using Cobre APIs

Authentication

Cobre Authentication API Guide#

Login cache and token lifecycle#

What expiration_time means in each scenario#

Token management best practices#

Recommendations#

Reference implementation (language-agnostic pseudocode)#

Handling a 401 response#

Allowed Actions on Authentication#

How to Get Started#

What to expect after using this API#

Cobre Authentication API Guide

Login cache and token lifecycle

What `expiration_time` means in each scenario

Token management best practices

Recommendations

Reference implementation (language-agnostic pseudocode)

Handling a 401 response

Allowed Actions on Authentication

How to Get Started

What to expect after using this API