JWT Authentication | Mercoa

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

1 from mercoa import Mercoa
2 from mercoa.entity_types import TokenGenerationOptions
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.get_token(
8     entity_id="ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
9     request=TokenGenerationOptions(
10         expires_in="1h",
11     ),
12 )

Entity User Level

POST

/entity/:entityId/user/:userId/token

1 from mercoa import Mercoa
2 from mercoa.entity_types import TokenGenerationOptions
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.user.get_token(
8     entity_id="ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
9     user_id="user_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
10     request=TokenGenerationOptions(
11         expires_in="1h",
12     ),
13 )

Entity Group Level

POST

/entityGroup/:entityGroupId/token

1 from mercoa import Mercoa
2 from mercoa.entity_types import TokenGenerationOptions
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity_group.get_token(
8     entity_group_id="entg_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
9     request=TokenGenerationOptions(
10         expires_in="1h",
11     ),
12 )

Entity Group User Level

POST

/entityGroup/:entityGroupId/user/:foreignId/token

1 from mercoa import Mercoa
2 from mercoa.entity_types import TokenGenerationOptions
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity_group.user.get_token(
8     entity_group_id="entg_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
9     foreign_id="MY-DB-ID-12345",
10     request=TokenGenerationOptions(
11         expires_in="1h",
12     ),
13 )

Token Revocation

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

POST

/organization/invalidateTokens

1 from mercoa import Mercoa
2 
3 client = Mercoa(
4     token="YOUR_TOKEN",
5 )
6 client.organization.invalidate_tokens()

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

1 from mercoa import Mercoa
2 from mercoa.entity_types import TokenGenerationOptions
3 
4 client = Mercoa(
5     token="YOUR_TOKEN",
6 )
7 client.entity.get_token(
8     entity_id="ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced",
9     request=TokenGenerationOptions(
10         expires_in="1h",
11         session_id="session_123",
12     ),
13 )

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

1 from mercoa import Mercoa
2 
3 client = Mercoa(
4     token="YOUR_TOKEN",
5 )
6 client.organization.invalidate_tokens(
7     session_id=["session_123", "session_456"],
8 )

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

Token Expiration: Set appropriate expiration times for your JWTs based on your security requirements. Shorter expiration times are generally more secure.
Session Management: Use session IDs when you need to track and manage user sessions, especially for features like “logout everywhere” or session invalidation.
Token Storage: Store JWTs securely in your frontend application or not at all. Consider using secure HTTP-only cookies or secure local storage mechanisms.
Token Refresh: Implement a token refresh mechanism for long-lived sessions to maintain security while providing a good user experience.