Authentication
Learn how to authenticate with the Wicket MDP API using JWT tokens
Wicket's API uses JSON Web Tokens (JWT) for authentication. Requests are authenticated using the bearer authorization scheme.
Overview
To authenticate API requests, you'll:
Generate a JWT token
Use your API Secret Key and Admin User UUID to create a signed JWT token.
Include the token in requests
Add the token to the Authorization header of your API requests.
Refresh tokens before expiry
Generate new tokens before they expire to maintain uninterrupted access.
Getting Your Credentials
You'll need two pieces of information to generate JWT tokens:
- API Secret Key: Your private key for signing tokens (keep this secure!)
- Admin User UUID: The UUID of a user with administrative privileges
Keep your API Secret Key safe! Never share it or place it in publicly accessible locations such as public code repositories or client-side code. This key grants full unrestricted access to your Wicket account.
Contact Wicket support to obtain these credentials.
JWT Token Structure
Wicket expects JWTs with the following structure:
Header
{
"alg": "HS256",
"typ": "JWT"
}The algorithm must be HS256 (HMAC with SHA-256).
Payload (Claims)
{
"exp": 1534414138,
"sub": "87882d7d-c230-4385-9231-e4fe9393f626",
"aud": "https://tenant-api.wicketcloud.com",
"iss": "https://your-website.com"
}Required claims:
exp: Unix timestamp for token expirationsub: UUID of your API admin useraud: Your Wicket MDP API URLiss: (Optional) Your issuer domain
For better security, keep the expiration date of your JWT tokens as short as possible (e.g., 15-60 minutes).
Generating Tokens
Here are examples of generating JWT tokens in different languages:
const jwt = require('jsonwebtoken');
const apiSecret = 'your-api-secret-key';
const adminUserUuid = '87882d7d-c230-4385-9231-e4fe9393f626';
const tenantUrl = 'https://tenant-api.wicketcloud.com';
const payload = {
exp: Math.floor(Date.now() / 1000) + (60 * 60), // 1 hour from now
sub: adminUserUuid,
aud: tenantUrl,
iss: 'https://your-website.com'
};
const token = jwt.sign(payload, apiSecret, { algorithm: 'HS256' });
console.log('JWT Token:', token);Install the library: npm install jsonwebtoken
require 'jwt'
api_secret = 'your-api-secret-key'
admin_user_uuid = '87882d7d-c230-4385-9231-e4fe9393f626'
tenant_url = 'https://tenant-api.wicketcloud.com'
payload = {
exp: Time.now.to_i + 3600, # 1 hour from now
sub: admin_user_uuid,
aud: tenant_url,
iss: 'https://your-website.com'
}
token = JWT.encode(payload, api_secret, 'HS256')
puts "JWT Token: #{token}"Install the library: gem install jwt
<?php
require 'vendor/autoload.php';
use Firebase\JWT\JWT;
$apiSecret = 'your-api-secret-key';
$adminUserUuid = '87882d7d-c230-4385-9231-e4fe9393f626';
$tenantUrl = 'https://tenant-api.wicketcloud.com';
$payload = [
'exp' => time() + 3600, // 1 hour from now
'sub' => $adminUserUuid,
'aud' => $tenantUrl,
'iss' => 'https://your-website.com'
];
$token = JWT::encode($payload, $apiSecret, 'HS256');
echo "JWT Token: " . $token;
?>Install the library: composer require firebase/php-jwt
Using Tokens in Requests
Include your JWT token in the Authorization header using the Bearer scheme:
curl -X GET https://tenant-api.wicketcloud.com/people \
-H "Authorization: Bearer <your-jwt-token>" \
-H "Content-Type: application/vnd.api+json"Token Scoping for Users
For API calls that access or update data on behalf of a specific user, it's highly recommended to use a token scoped for that user's person UUID in the sub claim.
This ensures:
- API resources are scoped to what the user has permissions to do
- Actions are properly attributed to the correct user
- Security is maintained through proper access control
When to Use User-Scoped Tokens
Use user-scoped tokens (person UUID in sub claim) for:
- User profile operations
- User-specific data access
- Operations that should respect user permissions
When to Use Admin Tokens
Reserve the API Admin user for:
- Management operations
- Actions that shouldn't be scoped to a specific user
- Administrative tasks requiring full access
Getting User UUIDs
There are several ways to obtain person UUIDs for user-scoped tokens:
1. SSO Authentication (Recommended)
When users authenticate via Single Sign-On (SSO), the person UUID is provided in the CAS authentication response. See the CAS Implementation Guide for complete integration examples.
2. API Lookup
You can retrieve people's UUIDs from the People endpoint by searching with email or other identifiers.
3. User Creation
When creating new users via the API, the person UUID is returned in the response.
Handling Authentication Errors
If authentication fails, you'll receive a 401 Unauthorized response:
{
"errors": [
{
"status": "401",
"code": "unauthorized",
"title": "Unauthorized",
"detail": "Invalid or expired JWT token"
}
]
}Common causes:
- Expired token (check the
expclaim) - Invalid signature (verify your API Secret Key)
- Malformed token structure
- Missing or invalid claims
Best Practices
- Keep tokens short-lived: Set expiration times of 15-60 minutes
- Secure your secret key: Never expose it in client-side code or public repositories
- Use user-scoped tokens: Scope tokens to specific users when possible
- Implement token refresh: Generate new tokens before expiration
- Monitor for 401 responses: Implement retry logic with fresh tokens