Generate Bearer Token

Generate a bearer token (JWT) for a customer. The token can be used for authentication in subsequent API calls. Either email or userId (external_user_id) must be provided to identify the customer.

Mutation

mutation GenerateHandbookCustomerBearerToken(
  $email: String
  $userId: String
  $expiresIn: Int
) {
  generateHandbookCustomerBearerToken(
    email: $email
    userId: $userId
    expiresIn: $expiresIn
  ) {
    token
    issuedAt
    expiresAt
    expiresIn
  }
}

Parameters

Parameter	Type	Required	Description
email	String	Conditional	Customer's email address (alternative to userId)
userId	String	Conditional	Customer's external user ID from the reseller system (alternative to email)
expiresIn	Int	No	Token expiration time in seconds. Default is 30 days (2,592,000 seconds).

Note: Either email OR userId must be provided (but not both).

Response

{
  "data": {
    "generateHandbookCustomerBearerToken": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "issuedAt": "2025-01-15T10:30:00Z",
      "expiresAt": "2025-02-14T10:30:00Z",
      "expiresIn": 2592000
    }
  }
}

Examples

Using Email

mutation {
  generateHandbookCustomerBearerToken(email: "[email protected]") {
    token
    issuedAt
    expiresAt
    expiresIn
  }
}

Using User ID

mutation {
  generateHandbookCustomerBearerToken(userId: "external_user_123") {
    token
    issuedAt
    expiresAt
    expiresIn
  }
}

Custom Expiration

mutation {
  generateHandbookCustomerBearerToken(
    userId: "external_user_123"
    expiresIn: 604800
  ) {
    token
    issuedAt
    expiresAt
    expiresIn
  }
}

This creates a token that expires in 7 days (604,800 seconds).

With Variables

mutation GenerateToken($userId: String, $expiresIn: Int) {
  generateHandbookCustomerBearerToken(
    userId: $userId
    expiresIn: $expiresIn
  ) {
    token
    issuedAt
    expiresAt
    expiresIn
  }
}

Variables:

{
  "userId": "external_user_123",
  "expiresIn": 2592000
}

Response Fields

Field	Type	Description
token	String!	JWT bearer token for customer authentication
issuedAt	String!	ISO 8601 timestamp when the token was issued
expiresAt	String!	ISO 8601 timestamp when the token will expire
expiresIn	Int!	Token expiration time in seconds

Error Responses

Customer Not Found

{
  "errors": [
    {
      "message": "Customer not found with email: [email protected]",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

Access Denied

{
  "errors": [
    {
      "message": "Customer not found or access denied",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

Missing Email or User ID

{
  "errors": [
    {
      "message": "Either email or userId must be provided",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Use Cases

• Customer Self-Service: Generate tokens for customers to access the Customer API
• Integration: Provide tokens to customers for integration with their systems
• Temporary Access: Create short-lived tokens for specific operations
• Token Rotation: Generate new tokens before old ones expire

Notes

• Requires reseller API key authentication
• The customer must belong to the authenticated reseller
• Default expiration is 30 days (2,592,000 seconds)
• Tokens can be used with the Customer API endpoint (/api/graphql-public)
• Tokens are JWT format and contain the customer's external user ID and email
• Multiple tokens can be active for the same customer
• Tokens should be stored securely and not shared publicly