Common Concepts

JWT Authentication

Mercoa uses JSON Web Tokens (JWTs) for frontend authentication. JWTs provide a secure and efficient way to authenticate users and control access to the Mercoa platform.

JWT Creation

JWTs can be created at multiple levels within your organization:

Entity Level

POST
/entity/:entityId/token
1curl -X POST https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/token \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "expiresIn": "1h"
6}'

Entity User Level

POST
/entity/:entityId/user/:userId/token
1curl -X POST https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/user/user_a0f6ea94-0761-4a5e-a416-3c453cb7eced/token \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "expiresIn": "1h"
6}'

Entity Group Level

POST
/entityGroup/:entityGroupId/token
1curl -X POST https://api.mercoa.com/entityGroup/entg_a0f6ea94-0761-4a5e-a416-3c453cb7eced/token \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "expiresIn": "1h"
6}'

Entity Group User Level

POST
/entityGroup/:entityGroupId/user/:foreignId/token
1curl -X POST https://api.mercoa.com/entityGroup/entg_a0f6ea94-0761-4a5e-a416-3c453cb7eced/user/MY-DB-ID-12345/token \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "expiresIn": "1h"
6}'

Token Revocation

All JWTs can be revoked at the organization level using the invalidateTokens endpoint:

POST
/organization/invalidateTokens
1curl -X POST https://api.mercoa.com/organization/invalidateTokens \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "sessionId": null
6}'

Session Management

JWTs can be created with a session ID, which is controlled by the platform. This allows for more granular control over token lifecycle:

POST
/entity/:entityId/token
1curl -X POST https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/token \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "expiresIn": "1h",
6  "sessionId": "session_123"
7}'

Sessions will automatically be invalidated if a new token for that session is not created within 24 hours. This time limit is subject to change.

To revoke tokens for a specific sessions:

POST
/organization/invalidateTokens
1curl -X POST https://api.mercoa.com/organization/invalidateTokens \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "sessionId": [
6    "session_123",
7    "session_456"
8  ]
9}'

Role-Based Access Control

JWTs work in conjunction with Mercoa’s Role-Based Access Control (RBAC) system. The roles and permissions assigned to a user are encoded in the JWT, ensuring that users can only access the resources and perform the actions they are authorized for.

For more information about roles and permissions, see our RBAC documentation.

Best Practices

  1. Token Expiration: Set appropriate expiration times for your JWTs based on your security requirements. Shorter expiration times are generally more secure.

  2. Session Management: Use session IDs when you need to track and manage user sessions, especially for features like “logout everywhere” or session invalidation.

  3. Token Storage: Store JWTs securely in your frontend application or not at all. Consider using secure HTTP-only cookies or secure local storage mechanisms.

  4. Token Refresh: Implement a token refresh mechanism for long-lived sessions to maintain security while providing a good user experience.