Pre-release — content may change.

Getting Started

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:

{
  "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 expiration
  • sub: UUID of your API admin user
  • aud: Your Wicket MDP API URL
  • iss: (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 exp claim)
  • Invalid signature (verify your API Secret Key)
  • Malformed token structure
  • Missing or invalid claims

Best Practices

  1. Keep tokens short-lived: Set expiration times of 15-60 minutes
  2. Secure your secret key: Never expose it in client-side code or public repositories
  3. Use user-scoped tokens: Scope tokens to specific users when possible
  4. Implement token refresh: Generate new tokens before expiration
  5. Monitor for 401 responses: Implement retry logic with fresh tokens

On this page