registerUser

Registration of a user. Requires special permission from Fluz to enable. Please contact support to enable this feature if needed. Fluz sets one of two registration modes for your application:

Direct registration, the default, creates the account at once and returns userId, accountId, and billingAddressId. It grants your application nothing; the user still has to complete the OAuth grant.
Consent mode, which Fluz enables per application, creates no user, account, or grant when you call it. It returns an authorizationUrl where the person signs up or logs in with the phone number you submitted and approves your application’s scopes. Fluz creates the grant when they approve. See Consent mode.

Contact Fluz support to change your application’s mode.

mutation {
  registerUser(
    firstName: String!
    lastName: String!
    phoneNumber: String!
    regionCode: String!
    emailAddress: String!
    dateOfBirth: String
    billingAddress: VirtualCardBillingAddressInput
    acceptCardholderAgreement: Boolean
    externalReferenceId: String
    steps: [RegisterUserEnrollmentStep!]
    callbackUrl: String
    deferSeatAssignment: Boolean
  ): RegisterUserResponse
}

Arguments

Argument	Type	Direct registration	Consent mode	Description
`firstName`	`String!`	Required	Required	The first name of user for registration.
`lastName`	`String!`	Required	Required	The last name of user for registration.
`phoneNumber`	`String!`	Required	Required	The phone number of user for registration.
`regionCode`	`String!`	Required	Required	The region code of phone number for registration.
`emailAddress`	`String!`	Required	Required	The email of user for registration.
`dateOfBirth`	`String`	Required	Ignored	The date of birth of user for registration.
`billingAddress`	`VirtualCardBillingAddressInput`	Required	Ignored	Billing address used for the user’s virtual card.
`acceptCardholderAgreement`	`Boolean`	Required, must be `true`	Ignored	Records the user’s acceptance of the cardholder agreement.
`externalReferenceId`	`String`	Ignored	Required	Your own ID for this person. Once the grant exists, pass it to `generateUserAccessToken`.
`steps`	`[RegisterUserEnrollmentStep!]`	Ignored	Optional	Setup steps the person completes after approving your application, in order: `KYC`, `FUNDING_SOURCE`, `PIN`. Defaults to none, so the flow ends at consent.
`callbackUrl`	`String`	Ignored	Optional	An `https` URL. When the flow finishes, the person sees a Back to app button that opens it. Outside production, `http://localhost` is also accepted.
`deferSeatAssignment`	`Boolean`	Optional	Ignored	When true, creates user without a rewards-network seat. Seat is assigned later at card redemption.

dateOfBirth, billingAddress, and acceptCardholderAgreement are nullable in the schema so that consent-mode calls can leave them out. Direct registration still requires them, but the error now comes back in data instead of failing GraphQL validation: a missing dateOfBirth or billingAddress returns ARG-0002, and a missing acceptCardholderAgreement returns ARG-0001.

Returns

RegisterUserResponse — represents the response returned from the registerUser mutation.

Field	Type	Description
`success`	`Boolean`	Whether registration completed.
`userId`	`UUID`	The created user. Absent on failure.
`accountId`	`UUID`	The created account. Absent on failure.
`billingAddressId`	`UUID`	The billing address created for the user. Absent on failure and in consent mode.
`status`	`RegisterUserStatus`	Consent mode only: `PENDING_CONSENT` or `LINKED`. Absent for direct registration.
`authorizationUrl`	`String`	Consent mode only. The link to show the person. Returned with `PENDING_CONSENT`.
`expiresAt`	`String`	Consent mode only. ISO 8601 time after which `authorizationUrl` stops working.
`error`	`RegisterUserError`	`message` and `code` describing the failure. Absent on success.

In consent mode, userId and accountId are returned only with LINKED.

Fluz enables consent mode per application. Contact Fluz support to turn it on for yours.

In consent mode, registerUser never creates a user and never checks whether the email address or phone number is already on Fluz. A person who is new to Fluz and a person who already has an account get the same response:

{
  "data": {
    "registerUser": {
      "success": true,
      "status": "PENDING_CONSENT",
      "authorizationUrl": "https://fluz.app/embedded?token=eyJhbGciOiJIUzI1NiIs...",
      "expiresAt": "2026-10-06T14:03:11.000Z",
      "userId": null,
      "accountId": null,
      "error": null
    }
  }
}

Show authorizationUrl to the person, either in the enrollment widget or as a link. They sign up or log in to their existing account with the phone number you submitted, which is pre-filled. Then they approve your application’s scopes and complete any steps you listed. When they approve, Fluz creates the grant, and from then on you call generateUserAccessToken with your externalReferenceId. If you subscribe to OAUTH_USER_LINKED, it usually tells you when the grant exists. It isn’t sent when the person had already granted your application the same scopes, so don’t rely on it alone: calling registerUser again returns LINKED once the grant exists. If the person’s Fluz account is already linked to your application under a different externalReferenceId, approval fails unless your application allows multiple external links. Approval also fails if the person signs in with a different phone number from the one you submitted. Fluz shows them an error, creates no grant, and registerUser keeps returning PENDING_CONSENT. Submit the phone number the person uses with Fluz.

Send authorizationUrl only to the person you registered, and treat it like a sign-in link. It carries the name, email address and phone number you submitted, and anyone who has it can open it.

If your application already holds a grant for the externalReferenceId, the response is LINKED, with the linked user’s userId and accountId and no link:

{
  "data": {
    "registerUser": {
      "success": true,
      "status": "LINKED",
      "authorizationUrl": null,
      "expiresAt": null,
      "userId": "8f5b8a2e-1c3d-4e5f-9a7b-2c4d6e8f0a1b",
      "accountId": "3a1c5e7f-9b2d-4f6a-8c0e-1d3f5a7b9c2e",
      "error": null
    }
  }
}

Each call returns a new link, and nothing is stored until the person approves. If a link expires or goes unused, call registerUser again for a new one. The consent flow doesn’t collect dateOfBirth, billingAddress, or acceptCardholderAgreement. After the grant, add the billing address with addVirtualCardAddress, and list KYC in steps if the person must verify their identity. Nothing is created on any error. The application and credential errors and the last AUTH-0025 case apply here too. The conflict codes AUTH-0026 and AUTH-0027 are never returned in consent mode.

Code	Error name	When	Message
`ARG-0002`	MissingArguments	One or more of `firstName`, `lastName`, `phoneNumber`, `regionCode`, `emailAddress`, `externalReferenceId` is empty	`Missing required arguments - externalReferenceId is required.`
`ARG-0001`	InvalidArguments	`steps` lists the same step twice	`steps must not contain duplicate values.`
`ARG-0001`	InvalidArguments	`callbackUrl` is not an `https` URL (`http://localhost` is accepted outside production)	`callbackUrl must be an https URL.`
`AUTH-0004`	InvalidPhoneNumber	`phoneNumber` is not a valid number for `regionCode`	`Please enter a valid phone number.`
`WIDGET-003`	MisconfiguredApplication	Your application has no OAuth client	`This application needs an OAuth client to issue registration consent links.`
`WIDGET-003`	MisconfiguredApplication	Your application has no type, API key, or secret for signing the link	`This application is not configured to issue registration consent links.`

WIDGET-003 means your application’s setup needs a change on Fluz’s side. Contact Fluz support rather than retrying. A steps value other than KYC, FUNDING_SOURCE, or PIN fails GraphQL validation, so it comes back in the errors array, not in data.

Errors

This mutation does not return GraphQL errors for business failures. Every failure comes back as HTTP 200 with success: false and a populated error object holding message and code. Two kinds of failure are exceptions. Authentication-middleware and rate-limit failures are rejected before the resolver runs and surface as HTTP errors. GraphQL validation failures, such as a wrong argument type or a steps value that is not a RegisterUserEnrollmentStep, come back in the GraphQL errors array with no registerUser result, so there is no error object to read.

{
  "data": {
    "registerUser": {
      "success": false,
      "error": {
        "message": "The email address you chose is already in use.",
        "code": "AUTH-0027"
      }
    }
  }
}

Branch on error.code, never on error.message — messages are prose and may be reworded, while codes are stable. The tables below list every code this mutation can return. Error name is the internal name for the code; it is not part of the response, and is shown only so support requests and log lines can be matched up.

Application and credential errors

Nothing was created. These apply in both modes. They indicate a problem with the calling application or its token, and will recur identically until the application setup changes.

Code	Error name	When	Message
`AUTH-0002`	InvalidCredentials	Called with Basic auth, or the bearer token carries no application	`User registration requires a valid user access (Bearer) token.`
`AUTH-0030`	ApplicationInactive	No application matches the token’s application id	`No application found for appId <appId>.`
`AUTH-0030`	ApplicationInactive	The application exists but is not `ACTIVE`	`Application <appId> is not active (current status: <status>).`
`AUTH-0008`	InvalidUserAccess	The bearer token belongs to a user other than the application’s owning developer	`The provided bearer token does not belong to the developer that owns this application.`
`AUTH-0022`	RegistrationNotAllowed	The application lacks the `can_register_user` capability	`This application is not permitted to register users. Please contact support to enable this capability.`
`AUTH-0022`	RegistrationNotAllowed	The application’s registration mode is not one Fluz supports	`Application <appId> has an unsupported register_user_mode. Please contact support.`

AUTH-0022 means registration has not been enabled for your application. Contact Fluz support rather than retrying.

Input errors

Direct registration. For consent mode, see Consent mode errors. Nothing was created. Fix the input and call again.

Code	Error name	When	Message
`ARG-0002`	MissingArguments	Direct registration: one or more of `firstName`, `lastName`, `phoneNumber`, `regionCode`, `emailAddress`, `dateOfBirth`, `billingAddress` is empty	`Missing required arguments - emailAddress, dateOfBirth are required.`
`ARG-0001`	InvalidArguments	Direct registration: `acceptCardholderAgreement` is not `true`	`acceptCardholderAgreement must be true`
`ARG-0001`	InvalidArguments	`billingAddress` fails schema validation	`Input validation error: <details>`
`AUTH-0004`	InvalidPhoneNumber	`phoneNumber` is not a valid number for `regionCode`	`Please enter a valid phone number.`
`AUTH-0004`	InvalidPhoneNumber	The number is valid but has no E.164 form	`Unable to format provided phone number.`
`AUTH-0004`	InvalidPhoneNumber	`phoneNumber` could not be parsed at all	`Invalid phone number format.`

The ARG-0002 message lists only the fields that were actually absent, and agrees in number (is required / are required). The ARG-0001 validation message appends the specific field errors, so read message for the detail even though you branch on code.

Conflicts

Direct registration only. Nothing was created. The email address or phone number already belongs to a Fluz user.

Code	Error name	When	Message
`AUTH-0027`	RegistrationEmailTaken	`emailAddress` already belongs to a Fluz user	`The email address you chose is already in use.`
`AUTH-0026`	RegistrationPhoneTaken	`phoneNumber` already belongs to a Fluz user	`The phone number you chose is already in use.`

Safe to retry with different values. Neither creates a partial user.

Registration failures

Registration could not be completed. Every case below returns the single code AUTH-0025 (UnsuccessfulRegistration) — the message is what distinguishes them.

When	Message
The duplicate email/phone check could not be completed	`Unable to verify whether the email address or phone number is already in use.`
Account creation failed	`Failed to create a new account for the user.`
User creation failed	`Failed to create the user record.`
Rewards-network seat setup failed	`Failed to create a seat for the new account.`
Registration finished without producing a complete user, account, and seat	`User registration did not complete successfully. Please try again.`
Any other unexpected failure	`Please try again again or contact support.`

AUTH-0025 is retryable, but it does not tell you whether the user was created — some stages run after the user and account already exist. Retry the same call, and treat the outcome as the answer:

Success means registration completed and the returned userId is the user to use.
AUTH-0027 or AUTH-0026 means an earlier attempt already created the user; look it up by email address or phone number instead of registering again.
The same AUTH-0025 message repeating means the failure is not transient. Contact Fluz support and quote the message text — it identifies the stage that failed.

API reference

Conventions

registerUser

Arguments

Returns

Errors

Application and credential errors

Input errors

Conflicts

Registration failures

​Arguments

​Returns

​Consent mode

​Consent mode errors

​Errors

​Application and credential errors

​Input errors

​Conflicts

​Registration failures

Arguments

Returns

Consent mode

Consent mode errors

Errors

Application and credential errors

Input errors

Conflicts

Registration failures