# ovok_sdk.resources.auth

Canonical page: https://docs.ovok.com/python-sdk/reference/resources/auth

The `ovok.auth` namespace: sign-in, registration and account management.

## MfaChallenge [#mfachallenge]

```python
MfaChallenge(profile_type: str, login_id: str, code_verifier: str)
```

Hand it back to `verify_mfa`: it carries the PKCE verifier the token exchange needs.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `profile_type` | `str` |  | The profile type the login started with. |
| `login_id` | `str` |  | The login the MFA code completes. |
| `code_verifier` | `str` |  | The PKCE verifier for the token exchange. |

## SignedIn [#signedin]

```python
SignedIn(session: Session, status: Literal['signed-in'] = 'signed-in')
```

The user is signed in.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `session` | `Session` |  | The new session. |
| `status` | `Literal['signed-in']` | `'signed-in'` | Always "signed-in". |

## MfaRequired [#mfarequired]

```python
MfaRequired(challenge: MfaChallenge, status: Literal['mfa-required'] = 'mfa-required')
```

The login needs a one-time code; pass `challenge` and the code to `verify_mfa`.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `challenge` | `MfaChallenge` |  | The pending MFA challenge. |
| `status` | `Literal['mfa-required']` | `'mfa-required'` | Always "mfa-required". |

## AuthResource [#authresource]

```python
AuthResource(
    http: HttpClient,
    tenant_code: str,
    session: UserSession | None,
    client_id: str | None = None,
)
```

User sign-in, registration and account management.

Created by `Ovok`; access it as `ovok.auth`. User sign-in needs a client built without
`client_secret`; `client_id` names the app for social sign-in and password resets.

**Examples**

```python
>>> result = ovok.auth.login(profile_type="Patient", email=email, password=password)
>>> if result.status == "mfa-required":
...     result = ovok.auth.verify_mfa(result.challenge, code)
```

### login() [#login]

```python
login(*, profile_type: ProfileType, email: str, password: str) -> LoginResult
```

Sign a user in with email and password.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `profile_type` | `ProfileType` |  | The profile to sign in as: "Patient", "Practitioner" or "RelatedPerson". |
| `email` | `str` |  | The account's email address. |
| `password` | `str` |  | The account's password. |

**Returns**

- `LoginResult`: `SignedIn` with the stored session, or `MfaRequired` when a one-time code is needed.

**Raises**

- `OvokConfigError`: The client signs in with `client_secret`.
- `OvokError`: The API rejects the login, such as for wrong credentials.

### verify_mfa() [#verify_mfa]

```python
verify_mfa(challenge: MfaChallenge, code: str) -> SignedIn
```

Finish a login with the one-time code.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `challenge` | `MfaChallenge` |  | The challenge from `MfaRequired`. |
| `code` | `str` |  | The one-time code the user entered. |

**Returns**

- `SignedIn`: `SignedIn` with the stored session.

**Raises**

- `OvokConfigError`: The client signs in with `client_secret`.

### register() [#register]

```python
register(registration: PatientRegistration) -> RegisterResult
```

Register a patient and sign them in.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `registration` | `PatientRegistration` |  | The patient's sign-up details. |

**Returns**

- `RegisterResult`: `SignedIn` with the stored session, or `ClinicianInvite` when the project routes the
- `RegisterResult`: email to a clinician invitation and no one is signed in.

**Raises**

- `OvokConfigError`: The client signs in with `client_secret`.
- `OvokValidationError`: The password and its confirmation differ.

### register_practitioner() [#register_practitioner]

```python
register_practitioner(registration: Registration) -> Session
```

Register a practitioner and sign them in.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `registration` | `Registration` |  | The practitioner's sign-up details. |

**Returns**

- `Session`: The stored session.

**Raises**

- `OvokConfigError`: The client signs in with `client_secret`.
- `OvokValidationError`: The password and its confirmation differ.

### social_login() [#social_login]

```python
social_login(
    provider: SocialProvider,
    *,
    internal_id: str,
    credential: Mapping[str, Any],
) -> Session
```

Sign in with an Apple or Google credential.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `provider` | `SocialProvider` |  | "apple" or "google". |
| `internal_id` | `str` |  | The app's internal ID for the user. |
| `credential` | `Mapping[str, Any]` |  | The provider's sign-in result as the API takes it, such as `{"idToken": ...}`. |

**Returns**

- `Session`: The stored session.

**Raises**

- `OvokConfigError`: The client has no `client_id`, or signs in with `client_secret`.

### current() [#current]

```python
current() -> Session | None
```

Return the stored session.

**Returns**

- `Session | None`: The session, or None when no user is signed in or the client is a machine client.

### me() [#me]

```python
me() -> dict[str, Any]
```

Read the signed-in user's profile and project.

**Returns**

- `dict[str, Any]`: The `auth/me` response.

### change_password() [#change_password]

```python
change_password(*, old_password: str, new_password: str) -> dict[str, Any]
```

Change the signed-in user's password.

The confirmation is the app's to check; Ovok Core never receives it.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `old_password` | `str` |  | The current password. |
| `new_password` | `str` |  | The new password. |

**Returns**

- `dict[str, Any]`: The API's response.

### reset_password() [#reset_password]

```python
reset_password(
    *,
    email: str,
    profile_type: ProfileType,
    client_id: str | None = None,
) -> dict[str, Any]
```

Send a password reset email.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `email` | `str` |  | The account's email address. |
| `profile_type` | `ProfileType` |  | The account's profile type. |
| `client_id` | `str \| None` | `None` | The app the email links to; defaults to the configured `client_id`. |

**Returns**

- `dict[str, Any]`: The API's response.

### complete_password_reset() [#complete_password_reset]

```python
complete_password_reset(*, reset_id: str, secret: str, password: str) -> dict[str, Any]
```

Set a new password from a reset link.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `reset_id` | `str` |  | The reset ID from the link. |
| `secret` | `str` |  | The reset secret from the link. |
| `password` | `str` |  | The new password. |

**Returns**

- `dict[str, Any]`: The API's response.

### delete_account() [#delete_account]

```python
delete_account(*, days: int, wipe: bool) -> dict[str, Any]
```

Schedule the signed-in account for deletion.

The account stays signed in.

**Parameters**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `days` | `int` |  | Days until the deletion. |
| `wipe` | `bool` |  | True to also delete the medical data. |

**Returns**

- `dict[str, Any]`: The API's response.

### logout() [#logout]

```python
logout() -> None
```

Sign out.

Ends the session on the server, and always locally, even when the server cannot be reached.

**Raises**

- `OvokConfigError`: The client signs in with `client_secret`.