Assign Token

Overview

Generate and verify user tokens on your own, then assign them to the IMKIT Chat Server for use. IMKIT will only handle messaging. This mode is suitable for applications that already have an existing authentication system and want full control over the token lifecycle.

Implementation flow:

1. Generate a custom token in your system
2. Use the /admin/clients API to create a Client, passing in your provided token and expirationDate
3. Subsequently, you can update the token via the “Update Token” API or revoke it via the “Revoke Token” API
4. Your system is responsible for the token verification logic

API Endpoint

Create a User and Assign an External Token

Create a new user and assign an access token generated by your system.

POST /admin/clients

Headers

Request Body

Example Request

JavaScript Example:

const response = await axios.post(
  "https://your-app.imkit.io/admin/clients",
  {
    _id: "user002",
    nickname: "John",
    avatarUrl: "https://example.com/avatar.jpg",
    issueAccessToken: false,
    token: "my-custom-token-xyz",
    expirationDate: "2025-06-30T12:00:00Z",
  },
  {
    headers: {
      "IM-API-KEY": process.env.IM_API_KEY,
      "Content-Type": "application/json",
    },
  }
);

cURL Example:

curl -X "POST" "https://your-app.imkit.io/admin/clients" \
     -H 'IM-API-KEY: {IM-API-KEY}' \
     -H 'Content-Type: application/json' \
     -d $'{
  "_id": "user002",
  "nickname": "John",
  "avatarUrl": "https://example.com/avatar.jpg",
  "issueAccessToken": false,
  "token": "my-custom-token-xyz",
  "expirationDate": "2025-06-30T12:00:00Z"
}'

Response

Success Response (200 OK)

Example Response

{
  "_id": "user002",
  "nickname": "John",
  "avatarUrl": "https://example.com/avatar.jpg",
  "issueAccessToken": false,
  "token": "my-custom-token-xyz",
  "expirationDate": "2025-06-30T12:00:00Z"
}

Error Response

400 Bad Request — Invalid request parameters

{
  "error": "INVALID_REQUEST",
  "message": "Missing required field: token"
}

401 Unauthorized — Invalid API key

{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key"
}

409 Conflict — User already exists

{
  "error": "USER_EXISTS",
  "message": "User with _id 'user002' already exists"
}

Use Cases

External Identity Integration

• SSO Integration: Bind tokens from an external authentication system to IMKIT users
• Custom Expiration: Set token validity periods based on business requirements

Token Management

• Token Rotation: Periodically update user access tokens to ensure security
• Multi-System Sync: Synchronize tokens issued by other systems to IMKIT

Notes

• Token Verification Responsibility: Your system is responsible for verifying token validity
• Expiration Time Management: Ensure the expirationDate is consistent with the token expiration time in your system
• Token Format: IMKIT does not restrict the token format, but it is recommended to use standard formats such as JWT
• Security: Ensure the token has sufficient entropy and an appropriate signing mechanism
• Update Frequency: It is recommended to proactively update tokens before they expire to avoid service interruptions
• Unified Authentication: It is recommended to integrate the IMKIT token with your existing authentication system and implement an automatic update mechanism
• Using the Token: After obtaining the token, pass it via the IM-Authorization header in subsequent API calls