Saltar al contenido principal

Tokens Bearer (JWT)

Los tokens Bearer (JWT) se usan para autenticar peticiones de usuario a la API de OrcaRail.

Iniciar sesión desde el panel​

La forma más sencilla de obtener un token Bearer es iniciar sesión en el panel. El panel usa el mismo endpoint de inicio de sesión y guarda el token por ti (en cookies); no tienes que gestionar tokens a mano cuando usas el panel.

Visión general​

Los tokens Bearer son JSON Web Tokens (JWT) que se obtienen cuando un usuario inicia sesión. Se usan en operaciones de cara al usuario en las que necesitas identificar qué usuario hace la petición.

Obtener un token Bearer​

Inicio de sesión​

Autentica a un usuario para recibir un token JWT:

POST /api/v1/auth/email/login

Cuerpo de la petición:

{
  "email": "[email protected]",
  "password": "secure-password"
}

Respuesta:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenExpires": 3600,
  "user": {
    "id": 1,
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Usar el token​

Incluye el token en la cabecera Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Ejemplo: iniciar sesión y usar el token​

JavaScript​

// Login
const loginResponse = await fetch(
  'https://api.orcarail.com/api/v1/auth/email/login',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: '[email protected]',
      password: 'secure-password',
    }),
  }
)

const { token, refreshToken, user } = await loginResponse.json()

// Store token securely (e.g., in memory, secure cookie, etc.)
localStorage.setItem('authToken', token)

// Use token for subsequent requests
const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
    }),
  }
)

cURL​

# Login
TOKEN=$(curl -X POST https://api.orcarail.com/api/v1/auth/email/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure-password"
  }' | jq -r '.token')

# Use token
curl https://api.orcarail.com/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

Caducidad del token​

Los tokens JWT caducan tras un periodo fijo (normalmente 1 hora). Cuando un token caduca, recibirás una respuesta 401 Unauthorized.

Token de refresco​

Usa el token de refresco para obtener un nuevo token de acceso:

POST /api/v1/auth/refresh
Authorization: Bearer YOUR_REFRESH_TOKEN

Respuesta:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "new_refresh_token_here",
  "tokenExpires": 3600
}

Ejemplo: refrescar el token​

async function refreshToken(refreshToken) {
  const response = await fetch('https://api.orcarail.com/api/v1/auth/refresh', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${refreshToken}`,
    },
  })

  if (!response.ok) {
    // Refresh token expired, need to login again
    throw new Error('Refresh token expired')
  }

  const { token, refreshToken: newRefreshToken } = await response.json()
  return { token, refreshToken: newRefreshToken }
}

// Use in your API client
async function apiRequest(url, options = {}) {
  let token = localStorage.getItem('authToken')

  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`,
    },
  })

  // If token expired, try to refresh
  if (response.status === 401) {
    const refreshToken = localStorage.getItem('refreshToken')
    const { token: newToken, refreshToken: newRefreshToken } =
      await refreshToken(refreshToken)

    localStorage.setItem('authToken', newToken)
    localStorage.setItem('refreshToken', newRefreshToken)

    // Retry request with new token
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${newToken}`,
      },
    })
  }

  return response
}

Cerrar sesión​

Cierra la sesión e invalida la sesión actual:

POST /api/v1/auth/logout
Authorization: Bearer YOUR_JWT_TOKEN

Respuesta: 204 No Content

Obtener el usuario actual​

Obtén información sobre el usuario autenticado:

GET /api/v1/auth/me
Authorization: Bearer YOUR_JWT_TOKEN

Respuesta:

{
  "id": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "role": "user",
  "status": "active"
}

Respuestas de error​

Token no válido​

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Token caducado​

{
  "statusCode": 401,
  "message": "Token expired",
  "error": "Unauthorized"
}

Falta la cabecera Authorization​

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Buenas prácticas de seguridad​

1. Guarda los tokens de forma segura​

  • Aplicaciones web: guárdalos en cookies HTTP-only o en memoria segura
  • Apps móviles: usa almacenamiento seguro (Keychain en iOS, Keystore en Android)
  • Aplicaciones de servidor: guárdalos en variables de entorno o en sistemas de gestión de secretos

2. Nunca expongas los tokens​

  • No registres los tokens en logs
  • No incluyas tokens en URLs
  • No subas tokens al control de versiones

3. Gestiona la caducidad de los tokens​

Implementa siempre la lógica de refresco para gestionar los tokens caducados sin problemas.

4. Usa HTTPS​

Usa siempre HTTPS en producción para proteger los tokens en tránsito.

Próximos pasos​