Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add bulk migration info #885

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add bulk migration info #885

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
81169e7
Add bulk migration info
bcbogdan Jan 2, 2025
f2435ea
Add a separate component to render request details
bcbogdan Jan 7, 2025
db99c5d
Add request details and update the migration doc
bcbogdan Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 168 additions & 0 deletions v3/docs/migration/_blocks/add-users-for-bulk-import-request.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
import { H2, H3, H4 } from "/src/components/Typography";
import { HTTPRequestCard } from "/src/components/Cards";

<HTTPRequestCard.DetailsModalHeader>
<HTTPRequestCard.DetailsModalDescription>
Stages users to be imported by a background cron job.
</HTTPRequestCard.DetailsModalDescription>
<HTTPRequestCard.DetailsModalDescription>
**Authorization**: Set the `api-key` header to the value of your **SuperTokens** Core API key.
</HTTPRequestCard.DetailsModalDescription>
</HTTPRequestCard.DetailsModalHeader>

<HTTPRequestCard.DetailsModalBody>

<H2>Request</H2>

<H3>Body Schema</H3>

| Name | Type | Description | Required |
|----------------|---------------------|-----------------------------------|----------|
| users | `Array` of `User` objects | The users that you want to import. The array has a limit of 10000 items. | Yes |


<H4>User</H4>

| Name | Type | Description | Required |
|----------------|------------------------|-------------------------------------------------------------------------------------------------|----------|
| externalUserId | `string` | ID that can be used to reference the users from your previous provider | No |
| userMetadata | `object` | An object with custom user information that can be used later on | No |
| userRoles | `array` of `strings` | The roles that will be used for authorization | No |
| totpDevices | `array` of `TotpDevice` | Time-based One-time Password device (TOTP) used for Multi-Factor Authentication | Yes |
| loginMethods | `array` of `LoginMethod` | The actual authentication methods and credentials | Yes |
##### TotpDevice

| Name | Type | Description | Required |
|------------|---------------------|-----------------------------------------------------------------------------|----------|
| secretKey | `string` | The secret key used to generate the TOTP codes. | Yes |
| period | `number` | The time period in seconds for which a TOTP code is valid. | Yes |
| skew | `number` | The allowable time skew to account for clock differences between the server and device. | Yes |
| deviceName | `string` | The name assigned to the TOTP device for identification purposes. | No |

##### LoginMethod

`LoginMethod` is a polymorphic type with multiple variants based on the `recipeId`. Each variant includes shared and specific fields.

###### EmailPassword

| Name | Type | Description | Required |
|-------------------------|-----------------------|-------------------------------------------------------------------------------------------------|----------|
| email | `string` | User's email address | Yes |
| passwordHash | `string` | Hashed password | Yes |
| hashingAlgorithm | `enum` (`"bcrypt"`, `"argon2"`, `"firebase_scrypt"`) | Hashing algorithm used. | Yes |
| recipeId | `string` | Must be `emailpassword` | Yes |
| tenantId | `string` | Identifier for the tenant (if you are using the `multi-tenancy` feature) | No |
| isVerified | `boolean` | Indicates whether the user's email has been verified | No |
| isPrimary | `boolean` | Indicates whether this is the user's primary authentication method | No |
| timeJoinedInMSSinceEpoch| `number` | Timestamp representing when the user joined, in milliseconds since the Unix epoch | No |

###### ThirdParty
| Name | Type | Description | Required |
|------------------|--------|-------------------------------|----------|
| recipeId | `string` | Must be `"thirdparty"` | Yes |
| email | `string` | User's email address | Yes |
| thirdPartyId | `string` | Identifier for the third party provider | Yes |
| thirdPartyUserId | `string` | User identifier from the third party provider | Yes |
| tenantId | `string` | Identifier for the tenant (if you are using the `multi-tenancy` feature) | No |
| isVerified | `boolean` | Indicates whether the user's email has been verified | No |
| isPrimary | `boolean` | Indicates whether this is the user's primary authentication method | No |
| timeJoinedInMSSinceEpoch| `number` | Timestamp representing when the user joined, in milliseconds since the Unix epoch | No |

###### Passwordless
| Name | Type | Description | Required |
|----------|--------|-----------------------|----------|
| recipeId | `string` | Must be `"passwordless"` | Yes |
| email | `string` | User's email address | One of `email` or `phoneNumber` must be provided |
| phoneNumber | `string` | User's phone number | One of `email` or `phoneNumber` must be provided |
| tenantId | `string` | Identifier for the tenant (if you are using the `multi-tenancy` feature) | No |
| isVerified | `boolean` | Indicates whether the user's email has been verified | No |
| isPrimary | `boolean` | Indicates whether this is the user's primary authentication method | No |
| timeJoinedInMSSinceEpoch| `number` | Timestamp representing when the user joined, in milliseconds since the Unix epoch | No |

<H3>Example</H3>

```bash
curl --location --request POST '^{coreInfo.uri}/bulk-import/add-users' \
--header 'api-key: ^{coreInfo.key}' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
users: [
{
"externalUserId": "user_2",
"userMetadata": {
"firstName": "John",
"lastName": "Doe",
"department": "Marketing"
},
"userRoles": ["editor"],
"loginMethods": [
{
"isVerified": true,
"isPrimary": true,
"timeJoinedInMSSinceEpoch": 1672617599000,
"recipeId": "thirdparty",
"email": "[email protected]",
"thirdPartyId": "google",
"thirdPartyUserId": "google_987654321"
}
]
}
]
}
```

<H2>Response</H2>

<H3>200</H3>
All the users have been added to the `bulk_import_users` table.

<H4>Example</H4>

```json
{
"status": "OK",
}
```

<H3>400</H3>

The request body was invalid.

<H4>Example</H4>

```json
```json
{
error: "Failed to add users for the bulk import. Please fix the error in the following users",
users: [
{
index: 11,
errors: ["No two loginMethods can have isPrimary as true."]
},
{
index: 15,
errors: ["email is required for recipeId emailpassword", "hashingAlgorithm must be one of 'bcrypt', 'argon2', or 'firebase_scrypt'."]
}
]
}
```

##### Errors

- Account linking must be enabled if more than one login method is provided for a user.
- Multitenancy must be enabled if a `tenantId` is other than `public.`
- No two `loginMethods` can have `isPrimary` as `true`.
- Invalid `appId` or `tenantId`.
- A valid `email` is required.
- A valid `passwordHash` is required.
- `hashingAlgorithm` must be one of 'bcrypt', 'argon2', or 'firebase_scrypt'.
- A valid `email` is required.
- `thirdPartyUserId` is required.
- A valid `email` or `phoneNumber` is required.


<H3>500</H3>

An internal server error occurred.

</HTTPRequestCard.DetailsModalBody>
147 changes: 147 additions & 0 deletions v3/docs/migration/_blocks/bulk-import-user-request.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
import { H2, H3, H4 } from "/src/components/Typography";
import { HTTPRequestCard } from "/src/components/Cards";

<HTTPRequestCard.DetailsModalHeader>
<HTTPRequestCard.DetailsModalDescription>
Creates one user at a time based on the request body.

</HTTPRequestCard.DetailsModalDescription>

<HTTPRequestCard.DetailsModalDescription>
**Authorization**: Set the `api-key` header to the value of your **SuperTokens** Core API key.
</HTTPRequestCard.DetailsModalDescription>

</HTTPRequestCard.DetailsModalHeader>

<HTTPRequestCard.DetailsModalBody>

<H2>Request</H2>

<H3>Body Schema</H3>

| Name | Type | Description | Required |
|----------------|------------------------|-------------------------------------------------------------------------------------------------|----------|
| externalUserId | `string` | ID that can be used to reference the users from your previous provider | No |
| userMetadata | `object` | An object with custom user information that can be used later on | No |
| userRoles | `array` of `strings` | The roles that will be used for authorization | No |
| totpDevices | `array` of `TotpDevice` | Time-based One-time Password device (TOTP) used for Multi-Factor Authentication | Yes |
| loginMethods | `array` of `LoginMethod` | The actual authentication methods and credentials | Yes |

<H4>TotpDevice</H4>

| Name | Type | Description | Required |
|------------|---------------------|-----------------------------------------------------------------------------|----------|
| secretKey | `string` | The secret key used to generate the TOTP codes. | Yes |
| period | `number` | The time period in seconds for which a TOTP code is valid. | Yes |
| skew | `number` | The allowable time skew to account for clock differences between the server and device. | Yes |
| deviceName | `string` | The name assigned to the TOTP device for identification purposes. | No |

<H4>LoginMethod</H4>

`LoginMethod` is a polymorphic type with multiple variants based on the `recipeId`. Each variant includes shared and specific fields.

##### EmailPassword

| Name | Type | Description | Required |
|-------------------------|-----------------------|-------------------------------------------------------------------------------------------------|----------|
| email | `string` | User's email address | Yes |
| passwordHash | `string` | Hashed password | Yes |
| hashingAlgorithm | `enum` (`"bcrypt"`, `"argon2"`, `"firebase_scrypt"`) | Hashing algorithm used. | Yes |
| recipeId | `string` | Must be `emailpassword` | Yes |
| tenantId | `string` | Identifier for the tenant (if you are using the `multi-tenancy` feature) | No |
| isVerified | `boolean` | Indicates whether the user's email has been verified | No |
| isPrimary | `boolean` | Indicates whether this is the user's primary authentication method | No |
| timeJoinedInMSSinceEpoch| `number` | Timestamp representing when the user joined, in milliseconds since the Unix epoch | No |

##### ThirdParty
| Name | Type | Description | Required |
|------------------|--------|-------------------------------|----------|
| recipeId | `string` | Must be `"thirdparty"` | Yes |
| email | `string` | User's email address | Yes |
| thirdPartyId | `string` | Identifier for the third party provider | Yes |
| thirdPartyUserId | `string` | User identifier from the third party provider | Yes |
| tenantId | `string` | Identifier for the tenant (if you are using the `multi-tenancy` feature) | No |
| isVerified | `boolean` | Indicates whether the user's email has been verified | No |
| isPrimary | `boolean` | Indicates whether this is the user's primary authentication method | No |
| timeJoinedInMSSinceEpoch| `number` | Timestamp representing when the user joined, in milliseconds since the Unix epoch | No |

##### Passwordless
| Name | Type | Description | Required |
|----------|--------|-----------------------|----------|
| recipeId | `string` | Must be `"passwordless"` | Yes |
| email | `string` | User's email address | One of `email` or `phoneNumber` must be provided |
| phoneNumber | `string` | User's phone number | One of `email` or `phoneNumber` must be provided |
| tenantId | `string` | Identifier for the tenant (if you are using the `multi-tenancy` feature) | No |
| isVerified | `boolean` | Indicates whether the user's email has been verified | No |
| isPrimary | `boolean` | Indicates whether this is the user's primary authentication method | No |
| timeJoinedInMSSinceEpoch| `number` | Timestamp representing when the user joined, in milliseconds since the Unix epoch | No |

<H3>Example</H3>

```bash
curl --location --request POST '^{coreInfo.uri}/bulk-import/import' \
--header 'api-key: ^{coreInfo.key}' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '
{
"externalUserId": "user_12345",
"userMetadata": {
"firstName": "Jane",
"lastName": "Doe",
"department": "Engineering"
},
"userRoles": ["admin"],
"totpDevices": [
{
"secretKey": "JBSWY3DPEHPK3PXP",
"period": 30,
"skew": 1,
"deviceName": "Main Device"
}
],
"loginMethods": [
{
"isVerified": true,
"isPrimary": true,
"timeJoinedInMSSinceEpoch": 1672531199000,
"recipeId": "emailpassword",
"email": "[email protected]",
"passwordHash": "$2b$12$KIXQeFz...",
"hashingAlgorithm": "bcrypt"
}
]
}
'
```

<H2>Response</H2>

<H3>200</H3>
The user has been successfully created.

<H4>Example</H4>

```json
{
"status": "OK",
"user": { /* User Object */ }
}
```

<H3>400</H3>

The request body was invalid.

<H4>Example</H4>

```json
{
"errors": ["No two loginMethods can have isPrimary as true.", "email is required for recipeId emailpassword", "hashingAlgorithm must be one of 'bcrypt', 'argon2', or 'firebase_scrypt'."]}
}
```

<H3>500</H3>

An internal server error occurred.

</HTTPRequestCard.DetailsModalBody>
55 changes: 55 additions & 0 deletions v3/docs/migration/_blocks/count-staged-users-request.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import { H2, H3, H4 } from "/src/components/Typography";
import { HTTPRequestCard } from "/src/components/Cards";

<HTTPRequestCard.DetailsModalHeader>
<HTTPRequestCard.DetailsModalDescription>
Returns the total number of users that were staged for import.
The value can be filtered by status.
</HTTPRequestCard.DetailsModalDescription>
<HTTPRequestCard.DetailsModalDescription>
**Authorization**: Set the `api-key` header to the value of your **SuperTokens** Core API key.
</HTTPRequestCard.DetailsModalDescription>
</HTTPRequestCard.DetailsModalHeader>

<HTTPRequestCard.DetailsModalBody>

<H2>Request</H2>

<H3>Query Parameters</H3>

| Name | Type | Description | Required |
|----------------|---------------------|-----------------------------------|----------|
| status | `enum` (`"NEW"`, `"PROCESSING"`, `"FAILED"`) | Can be used to count only users with a specific status. | No |

<H3>Example</H3>

```bash
curl --location --request GET '^{coreInfo.uri}/bulk-import/users/count?status=PROCESSING' \
--header 'api-key: ^{coreInfo.key}' \
--header 'Content-Type: application/json; charset=utf-8' \
```

<H2>Response</H2>

<H3>200</H3>

The users have been successfully retrieved.

<H4>Example</H4>

```json
{
"status": "OK",
"count": "<number>",
}
```

<H3>400</H3>

The tenant or the specified app have not been found.

<H3>500</H3>

An internal server error occurred.

</HTTPRequestCard.DetailsModalBody>
Loading