Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt

Use this file to discover all available pages before exploring further.

Use createSelfServiceCenterLoginTokenV2 when you want to send a customer directly into the Firmhouse Self Service Center from your own app, email, or support tool without asking them to request a login email first. The mutation looks up a completed subscription in your project by email address, creates a short-lived Self Service Center login token, and returns a URL that includes the token. Redirect the customer to that URL for immediate login.

​
Requirements

  • A Firmhouse API access token with write access. Create one in Settings > Integrations > Access Tokens in your Firmhouse project.
  • The customer’s email address must match a completed subscription in the same Firmhouse project.
  • The mutation should be called from your backend. Do not expose a write API access token in browser code.

​
Create the token

Send a GraphQL request to the Firmhouse API and pass the customer’s email address to createSelfServiceCenterLoginTokenV2. 
mutation CreateSelfServiceCenterLoginToken($email: String!) {
  createSelfServiceCenterLoginTokenV2(input: { email: $email }) {
    selfServiceCenterLoginToken {
      token
      expiresAt
      returnUrlWithToken
    }
    errors {
      attribute
      message
    }
  }
}
Use variables for the email address: 
{
  "email": "customer@example.com"
}
Example request: 
curl https://portal.firmhouse.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Project-Access-Token: YOUR_PROJECT_ACCESS_TOKEN" \
  -d '{
    "query": "mutation CreateSelfServiceCenterLoginToken($email: String!) { createSelfServiceCenterLoginTokenV2(input: { email: $email }) { selfServiceCenterLoginToken { token expiresAt returnUrlWithToken } errors { attribute message } } }",
    "variables": {
      "email": "customer@example.com"
    }
  }'

​
Redirect the customer

Use returnUrlWithToken from the response as the destination URL: 
{
  "data": {
    "createSelfServiceCenterLoginTokenV2": {
      "selfServiceCenterLoginToken": {
        "token": "generated-token",
        "expiresAt": "2026-05-15T16:00:00Z",
        "returnUrlWithToken": "https://your-project.example.com/en/your-project/self-service/token_login?token=generated-token"
      },
      "errors": []
    }
  }
}
Redirect the customer to returnUrlWithToken. Firmhouse validates the token, starts the customer’s Self Service Center session, and shows the Self Service Center for the matched subscription. If you only need the raw token, you can build the login URL yourself by adding it as the token query parameter to your project’s Self Service Center token login URL: 
https://<your-self-service-center-domain>/<locale>/<project-path>/self-service/token_login?token=<token>
In most integrations, using returnUrlWithToken is safer because Firmhouse returns the correct project host, locale, project path, and token parameter for the matched subscription.

​
Handle errors and expiry

Check both top-level GraphQL errors and the mutation payload’s errors field. When the API returns a mutation payload but cannot create a login token, selfServiceCenterLoginToken is null and the payload’s errors field contains the validation details. When the email address does not match a completed subscription in the project, the API can return a top-level GraphQL error before returning the mutation payload. Handle that response as a failed token creation and ask the customer to use the email address connected to their subscription. Self Service Center login tokens expire after 4 hours. Generate the token shortly before redirecting the customer.