11. User Activation

Reference: {#RefActivation}

Author: Artyom Kazak

A user is called activated they have a verified identity – e.g. a phone number that has been verified via a text message, or an email address that has been verified by sending an activation code to it.

A user that has been provisioned via single sign-on is always considered to be activated.

11.1. Activated vs. non-activated users

Non-activated users can not connect to others, nor can connection requests be made to anonymous accounts from verified accounts. As a result:

A non-activated user cannot add other users to conversations. The only way to participate in a conversation is to either create a new conversation with link access or to use a link provided by another user.

The only flow where it makes sense for non-activated users to exist is the wireless flow used for guest rooms

11.2. API

11.2.1. Requesting an activation code

During the standard registration flow, the user submits an email address or phone number by making a request to POST /activate/send. A six-digit activation code will be sent to that email address / phone number. Sample request and response:

POST /activate/send

{
    // Either 'email' or 'phone'
    "phone": "+1234567890"
}

200 OK

The user can submit the activation code during registration to prove that they own the email address / phone number.

The same POST /activate/send endpoint can be used to re-request an activation code. Please use this ability sparingly! To avoid unnecessary activation code requests, users should be warned that it might take up to a few minutes for an email or text message to arrive.

11.2.2. Activating an existing account

If the account has not been activated during verification, it can be activated afterwards by submitting an activation code to POST /activate. Sample request and response:

POST /activate

{
    // One of 'phone', 'email', or 'key'
    "phone": "+1234567890",

    // 6-digit activation code
    "code": "123456",

    // Verify the 'code' but don't activate the account (the 3-attempt limit
    // on failed verification attempts still applies)
    "dryrun": false
}

200 OK

{
    "phone": "+1234567890",

    // Whether it is the first successful activation for the user
    "first": true
}

If the email or phone has been verified already, POST /activate will return status code 204 No Content. If the code is invalid, POST /activate will return status code 404 Not Found with "label": "invalid-code".

There is a maximum of 3 activation attempts per activation code. On the third failed attempt the code is invalidated and a new one must be requested.

11.2.3. Activation event

When the user becomes activated, they receive an event:

{
    "type": "user.activate",
    "user": <self profile>
}

11.2.4. Detecting activation in the self profile

In addition to the activation event, activation can be detected by polling the self profile:

GET /self

{
    "accent_id": 0,
    "assets": [],
    "email": "pink@example.com",
    "id": "2f7e582b-9d99-4d50-bbb0-e659d63491d9",
    "locale": "en",
    "managed_by": "wire",
    "name": "Pink",
    "picture": []
}

If the profile includes "email" or "phone", the account is activated.

11.3. Automating activation via email

Our email verification messages contain headers that can be used to automate the activation process.

An email caused by POST /activate/send will contain this set of headers:

X-Zeta-Purpose: Verification
X-Zeta-Code: 123456

An email caused by POST /register will contain this set of headers (the opaque "key" might be used instead of "email" in the POST /activate request):

X-Zeta-Purpose: Activation
X-Zeta-Key: ...
X-Zeta-Code: 123456

11.4. Phone/email whitelist

The backend can be configured to only allow specific phone number prefixes and email address domains to register. The following options have to be set in brig.yaml:

optSettings:
  setAllowlistEmailDomains:
    - wire.com
    - example.com
    - notagoodexample.com
  setAllowlistPhonePrefixes:
    - "+49"
    - "+1555555"

When those options are present, the backend will match every activation request against these lists.

If an email address or phone number are rejected by the whitelist, POST /activate/send or POST /register will return 403 Forbidden:

{
    "code": 403,
    "label": "unauthorized",
    "message": "Unauthorized e-mail address or phone number."
}