Log customers into the Self Service Center with a token

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 and starts the customer’s Self Service Center session. When the email address has access to multiple subscriptions, Firmhouse uses the normal subscription chooser unless you add a target as described below.

Target one of the customer’s subscriptions

When the email address has access to multiple subscriptions, use the optional subscription_id query parameter to open a specific subscription directly. To let the customer request their own magic link, include the target on the Customer Portal login-page URL:

https://<your-self-service-center-domain>/<locale>/<project-path>/self-service/login?subscription_id=<subscription-id>

Firmhouse preserves the target when the customer submits their email address and includes it in the emailed magic-link URL. When you generate the token through the API instead, add the target to returnUrlWithToken:

https://<your-self-service-center-domain>/<locale>/<project-path>/self-service/token_login?token=<token>&subscription_id=<subscription-id>

Use the Firmhouse subscription ID returned by the API. Firmhouse only uses the target when it belongs to the email address authenticated by the login token, including subscriptions in a linked Self Service Center login project. Missing, invalid, or inaccessible subscription IDs use the normal post-login routing and do not reveal subscription data. If the URL also includes a valid redirect_to path, Firmhouse opens that path for the targeted subscription. This can only be a path inside the targeted subscription’s Self Service Center; external redirect URLs are ignored. 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.

​Requirements

​Create the token

​Redirect the customer

​Target one of the customer’s subscriptions

​Handle errors and expiry

​Related

Requirements

Create the token

Redirect the customer

Target one of the customer’s subscriptions

Handle errors and expiry

Related