# Login

## Start Beeper app setup

`$client->app->login->start(): LoginStartResponse`

**post** `/v1/app/setup/start`

Start setting up Beeper Desktop or Beeper Server. The flow supports existing Beeper accounts and new account creation.

### Returns

- `LoginStartResponse`

  - `string setupRequestID`

    Setup request ID to use in the next sign-in step.

  - `list<string> signInMethods`

    Available sign-in methods for this setup request.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$response = $client->app->login->start();

var_dump($response);
```

#### Response

```json
{
  "setupRequestID": "setupRequestID",
  "signInMethods": [
    "string"
  ]
}
```

## Send setup sign-in code

`$client->app->login->email(string email, string setupRequestID): void`

**post** `/v1/app/setup/email`

Send a sign-in code to the user email address for app setup.

### Parameters

- `email: string`

  Email address to send the sign-in code to.

- `setupRequestID: string`

  Setup request ID returned by the start step.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$result = $client->app->login->email(
  email: 'dev@stainless.com', setupRequestID: 'setupRequestID'
);

var_dump($result);
```

## Complete setup sign-in with code

`$client->app->login->response(string response, string setupRequestID): LoginResponseResponse`

**post** `/v1/app/setup/response`

Finish setup sign-in with the code sent to the user email address. If the user needs a new account, the response includes account creation copy and username suggestions.

### Parameters

- `response: string`

  Sign-in code from the user email.

- `setupRequestID: string`

  Setup request ID returned by the start step.

### Returns

- `LoginResponseResponse`

  - `AppSetupCompleteResponse`

    - `Matrix matrix`

      Account credentials for first-party app setup.

    - `Session session`

      Current app sign-in and encrypted messaging setup state after sign-in.

  - `AppSetupRegistrationRequiredResponse`

    - `Copy copy`

      Copy to display during account creation.

    - `string leadToken`

      Registration token returned by Beeper.

    - `true registrationRequired`

      Indicates that the user needs to create a Beeper account.

    - `string setupRequestID`

      Setup request ID to use when creating the account.

    - `?list<string> usernameSuggestions`

      Suggested usernames for the new account.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$response = $client->app->login->response(
  response: 'response', setupRequestID: 'setupRequestID'
);

var_dump($response);
```

#### Response

```json
{
  "matrix": {
    "accessToken": "accessToken",
    "deviceID": "deviceID",
    "homeserver": "homeserver",
    "userID": "userID"
  },
  "session": {
    "e2ee": {
      "crossSigning": true,
      "firstSyncDone": true,
      "hasBackedUpRecoveryKey": true,
      "initialized": true,
      "keyBackup": true,
      "secrets": {
        "masterKey": true,
        "megolmBackupKey": true,
        "recoveryKey": true,
        "selfSigningKey": true,
        "userSigningKey": true
      },
      "secretStorage": true,
      "verified": true,
      "recoveryKeyGeneratedAt": 0
    },
    "state": "needs-login",
    "matrix": {
      "deviceID": "deviceID",
      "homeserver": "homeserver",
      "userID": "userID"
    },
    "verification": {
      "id": "id",
      "availableActions": [
        "accept"
      ],
      "direction": "incoming",
      "methods": [
        "qr"
      ],
      "purpose": "login",
      "state": "requested",
      "error": {
        "code": "code",
        "reason": "reason"
      },
      "otherDevice": {
        "id": "id",
        "name": "name"
      },
      "otherUserID": "otherUserID",
      "qr": {
        "data": "data"
      },
      "sas": {
        "emojis": "emojis",
        "decimals": "decimals"
      }
    }
  }
}
```

## Create account for setup

`$client->app->login->register(true acceptTerms, string leadToken, string setupRequestID, string username): LoginRegisterResponse`

**post** `/v1/app/setup/register`

Create a Beeper account after the user chooses a username and accepts the Terms of Use.

### Parameters

- `acceptTerms: true`

  Confirms that the user agreed to our [terms of use](https://www.beeper.com/terms-onboarding) and has read our [privacy policy](https://www.beeper.com/privacy).

- `leadToken: string`

  Registration token returned by Beeper.

- `setupRequestID: string`

  Setup request ID returned by the start step.

- `username: string`

  Username selected by the user.

### Returns

- `LoginRegisterResponse`

  - `Matrix matrix`

    Account credentials for first-party app setup.

  - `Session session`

    Current app sign-in and encrypted messaging setup state after sign-in.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$response = $client->app->login->register(
  acceptTerms: true,
  leadToken: 'leadToken',
  setupRequestID: 'setupRequestID',
  username: 'x',
);

var_dump($response);
```

#### Response

```json
{
  "matrix": {
    "accessToken": "accessToken",
    "deviceID": "deviceID",
    "homeserver": "homeserver",
    "userID": "userID"
  },
  "session": {
    "e2ee": {
      "crossSigning": true,
      "firstSyncDone": true,
      "hasBackedUpRecoveryKey": true,
      "initialized": true,
      "keyBackup": true,
      "secrets": {
        "masterKey": true,
        "megolmBackupKey": true,
        "recoveryKey": true,
        "selfSigningKey": true,
        "userSigningKey": true
      },
      "secretStorage": true,
      "verified": true,
      "recoveryKeyGeneratedAt": 0
    },
    "state": "needs-login",
    "matrix": {
      "deviceID": "deviceID",
      "homeserver": "homeserver",
      "userID": "userID"
    },
    "verification": {
      "id": "id",
      "availableActions": [
        "accept"
      ],
      "direction": "incoming",
      "methods": [
        "qr"
      ],
      "purpose": "login",
      "state": "requested",
      "error": {
        "code": "code",
        "reason": "reason"
      },
      "otherDevice": {
        "id": "id",
        "name": "name"
      },
      "otherUserID": "otherUserID",
      "qr": {
        "data": "data"
      },
      "sas": {
        "emojis": "emojis",
        "decimals": "decimals"
      }
    }
  }
}
```

# Verification

# Recovery Key

## Verify with recovery key

`$client->app->login->verification->recoveryKey->verify(string recoveryKey): RecoveryKeyVerifyResponse`

**post** `/v1/app/setup/verification/recovery-key`

Unlock encrypted messages with the user recovery key.

### Parameters

- `recoveryKey: string`

  Recovery key saved by the user.

### Returns

- `RecoveryKeyVerifyResponse`

  - `Session session`

    Current app sign-in and encrypted messaging setup state.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$response = $client->app->login->verification->recoveryKey->verify(
  recoveryKey: 'x'
);

var_dump($response);
```

#### Response

```json
{
  "session": {
    "e2ee": {
      "crossSigning": true,
      "firstSyncDone": true,
      "hasBackedUpRecoveryKey": true,
      "initialized": true,
      "keyBackup": true,
      "secrets": {
        "masterKey": true,
        "megolmBackupKey": true,
        "recoveryKey": true,
        "selfSigningKey": true,
        "userSigningKey": true
      },
      "secretStorage": true,
      "verified": true,
      "recoveryKeyGeneratedAt": 0
    },
    "state": "needs-login",
    "matrix": {
      "deviceID": "deviceID",
      "homeserver": "homeserver",
      "userID": "userID"
    },
    "verification": {
      "id": "id",
      "availableActions": [
        "accept"
      ],
      "direction": "incoming",
      "methods": [
        "qr"
      ],
      "purpose": "login",
      "state": "requested",
      "error": {
        "code": "code",
        "reason": "reason"
      },
      "otherDevice": {
        "id": "id",
        "name": "name"
      },
      "otherUserID": "otherUserID",
      "qr": {
        "data": "data"
      },
      "sas": {
        "emojis": "emojis",
        "decimals": "decimals"
      }
    }
  }
}
```

# Reset

## Create new recovery key

`$client->app->login->verification->recoveryKey->reset->create(?string existingRecoveryKey): ResetNewResponse`

**post** `/v1/app/setup/verification/recovery-key/reset`

Create a new recovery key when the user cannot use the existing one.

### Parameters

- `existingRecoveryKey?:optional string`

  Existing recovery key, if the user has it.

### Returns

- `ResetNewResponse`

  - `string recoveryKey`

    New recovery key. Show it once and ask the user to save it.

  - `Session session`

    Current app sign-in and encrypted messaging setup state after creating the new recovery key.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$reset = $client->app->login->verification->recoveryKey->reset->create(
  existingRecoveryKey: 'existingRecoveryKey'
);

var_dump($reset);
```

#### Response

```json
{
  "recoveryKey": "recoveryKey",
  "session": {
    "e2ee": {
      "crossSigning": true,
      "firstSyncDone": true,
      "hasBackedUpRecoveryKey": true,
      "initialized": true,
      "keyBackup": true,
      "secrets": {
        "masterKey": true,
        "megolmBackupKey": true,
        "recoveryKey": true,
        "selfSigningKey": true,
        "userSigningKey": true
      },
      "secretStorage": true,
      "verified": true,
      "recoveryKeyGeneratedAt": 0
    },
    "state": "needs-login",
    "matrix": {
      "deviceID": "deviceID",
      "homeserver": "homeserver",
      "userID": "userID"
    },
    "verification": {
      "id": "id",
      "availableActions": [
        "accept"
      ],
      "direction": "incoming",
      "methods": [
        "qr"
      ],
      "purpose": "login",
      "state": "requested",
      "error": {
        "code": "code",
        "reason": "reason"
      },
      "otherDevice": {
        "id": "id",
        "name": "name"
      },
      "otherUserID": "otherUserID",
      "qr": {
        "data": "data"
      },
      "sas": {
        "emojis": "emojis",
        "decimals": "decimals"
      }
    }
  }
}
```

## Confirm new recovery key

`$client->app->login->verification->recoveryKey->reset->confirm(string recoveryKey): ResetConfirmResponse`

**post** `/v1/app/setup/verification/recovery-key/reset/confirm`

Confirm that the new recovery key should be used for this account.

### Parameters

- `recoveryKey: string`

  New recovery key returned by the reset step.

### Returns

- `ResetConfirmResponse`

  - `Session session`

    Current app sign-in and encrypted messaging setup state.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$response = $client->app->login->verification->recoveryKey->reset->confirm(
  recoveryKey: 'x'
);

var_dump($response);
```

#### Response

```json
{
  "session": {
    "e2ee": {
      "crossSigning": true,
      "firstSyncDone": true,
      "hasBackedUpRecoveryKey": true,
      "initialized": true,
      "keyBackup": true,
      "secrets": {
        "masterKey": true,
        "megolmBackupKey": true,
        "recoveryKey": true,
        "selfSigningKey": true,
        "userSigningKey": true
      },
      "secretStorage": true,
      "verified": true,
      "recoveryKeyGeneratedAt": 0
    },
    "state": "needs-login",
    "matrix": {
      "deviceID": "deviceID",
      "homeserver": "homeserver",
      "userID": "userID"
    },
    "verification": {
      "id": "id",
      "availableActions": [
        "accept"
      ],
      "direction": "incoming",
      "methods": [
        "qr"
      ],
      "purpose": "login",
      "state": "requested",
      "error": {
        "code": "code",
        "reason": "reason"
      },
      "otherDevice": {
        "id": "id",
        "name": "name"
      },
      "otherUserID": "otherUserID",
      "qr": {
        "data": "data"
      },
      "sas": {
        "emojis": "emojis",
        "decimals": "decimals"
      }
    }
  }
}
```