Empezar

Autenticación

Argentive Card soporta dos formas de autenticación según cómo se use: API keys sk_* para integraciones server-to-server, y OAuth 2.1 + PKCE para agentes que actúan en nombre de un usuario final.

API keys (server-to-server)

Las API keys son el método estándar para integrar tu plataforma. Se incluyen en cada request en el header Authorization.

header
Authorization: Bearer sk_live_4242abcdef0123456789...

Tipos de key

  • sk_test_… — Test mode. No mueve plata real ni emite cards reales en la red del issuer. Acepta tarjetas de prueba. Ideal para CI/CD.
  • sk_live_… — Live mode. Toda transacción es real: hold real en MP/dLocal, card emitida en la red del issuer, recibo AFIP/SAT.
Nunca expongas sk_live_
Las keys sk_live_ dan acceso al dinero real de tus cardholders. Nunca las metas en código de cliente (frontend, mobile, browser extension). Si te filtraste una, rotala desde el dashboard inmediatamente.

Crear y rotar keys

Desde el dashboard de Argentive (sección API Keys) podés:

  • Crear una nueva key sk_test_ o sk_live_.
  • Asignarle un label y permisos granulares por endpoint.
  • Rotarla — la key vieja sigue funcionando por 24h para evitar downtime.
  • Ver el último uso, IP de origen y rate-limit consumido.

Rate limit

Cada API key tiene un límite de 1000 requests / hora por defecto. Si lo superás, recibís un 429 Too Many Requests con headers:

response headers
X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1719234000   # epoch seconds
Retry-After:           38

Para volúmenes mayores (plataformas B2B con muchos cardholders activos) escribinos para subir el límite — es sin costo extra.

OAuth 2.1 + PKCE (Connect with Argentive)

Si tu app le permite a un usuario final conectar SU cuenta de Argentive Card (en vez de que tu app emita en su nombre), usás OAuth 2.1 + PKCE. Cada cliente OAuth solo ve las cards que él mismo creó — aislamiento por client_id.

Endpoints

oauth metadata
Authorization endpoint:  https://mcp.argentive.card/authorize
Token endpoint:          https://mcp.argentive.card/token
Discovery (RFC 8414):    https://mcp.argentive.card/.well-known/oauth-authorization-server
Code challenge method:   S256 (PKCE obligatorio)
Access token TTL:        24 horas
Refresh token:           long-lived con rotación, refresh lazy on 401

Flow

oauth flow
1. Tu app genera code_verifier + code_challenge (S256)
2. Redirige al user a /authorize?client_id=...&code_challenge=...&redirect_uri=...&scope=cards.read+cards.write
3. User autoriza en Argentive. Vuelve a tu redirect_uri con ?code=...
4. Tu backend hace POST /token con code + code_verifier
5. Recibís { access_token, refresh_token, expires_in: 86400 }
6. Usás access_token en lugar de sk_live_ en el Authorization header

Scopes

  • cards.read — listar y leer cards.
  • cards.write — crear y cerrar cards.
  • cards.details — leer PAN/CVV (alto privilegio, auditado).
  • cardholders.read — leer datos del cardholder.
  • cardholders.write — actualizar datos del cardholder.
  • transactions.read — listar transacciones.
  • webhooks.manage — administrar endpoints de webhooks.

Refresh

curl
curl -s -X POST https://mcp.argentive.card/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH" \
  -d "client_id=$CLIENT_ID"

# {
#   "access_token":  "at_...",
#   "refresh_token": "rt_..."     ← rotación: el viejo se invalida
#   "expires_in":    86400,
#   "token_type":    "Bearer"
# }
Nota
El refresh_token rota en cada uso: el anterior queda inválido. Si dos clientes usan el mismo refresh en paralelo, uno va a fallar con invalid_grant — esperado.

¿Cuándo uso cuál?

  • API key si tu app emite cards para sus propios usuarios (ej. una plataforma de booking que crea cards para que sus agentes paguen reservas).
  • OAuth si tu app le permite a un user final usar SU cuenta de Argentive Card (ej. un IDE que se conecta para que el dev pague AWS desde su propia billetera). El usuario aprueba qué scopes le da a tu app.