REST Endpoints
Introduction
It's recommended to use one of the client libraries, but if for some reason you can't use them, TurboCore provides a REST API for authentication. You can use this API to sign up, sign in, and log out users. You can also use this API to get a user's information and refresh their JWT token.
Endpoints that require authentication will be marked with a π. See Using the REST API for more information.
GET /api/auth/user π
You can get a user's information by sending a GET request to the /api/auth/user
endpoint.
Method: GET
Endpoint: /api/auth/get-user
Request Body: None
Response Body:
Property Name | Type | Description |
---|---|---|
uid | string | The UID of the user |
string | The email of the user | |
created_at | integer | The date the user was created in UNIX epoch time |
updated_at | integer | The date the user was last updated in UNIX epoch time |
last_login | integer | null | The date the user last logged in in UNIX epoch time |
active | boolean | Whether the user is active |
email_verified | boolean | Whether the user's email is verified |
metadata | string | A JSON string to store additional metadata about the user |
Example response:
{
"uid": "710f7e29-4082-4421-b9b5-49f56a393832",
"email": "[email protected]",
"created_at": 1633040000,
"updated_at": 1633040000,
"last_login": 1633040000,
"email_verified": true,
"metadata": "{\"role\": \"admin\", \"name\": \"John Doe\", \"age\": 21}"
}
Common Errors:
- NOT_AUTHENTICATED: The
Authorization
header is missing or invalid - USER_NOT_FOUND: The requested user was not found
POST /api/auth/user/login
You can sign in a user by sending a POST request to the /api/auth/user/login
endpoint.
Method: POST
Endpoint: /api/auth/user/login
Request Body:
Property Name | Type | Description |
---|---|---|
string | The email of the user | |
password | string | The password of the user |
Response Body:
Property Name | Type | Description |
---|---|---|
uid | string | The UID of the requested user |
token | string | The JWT token of requested the user |
expiry | string | The date the token expires in UNIX epoch time |
refresh_token | string | A token used to get a new JWT token from TurboCore |
email_verified | boolean | Whether the user's email has been verified |
metadata | string | A JSON string to store additional metadata about the user |
Example response:
{
"uid": "710f7e29-4082-4421-b9b5-49f56a393832",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNjc3NDgwNDg3IiwiaXNzIjoiVHVyYm9Db3JlIiwidHlwZSI6ImF0IiwidWlkIjoiRGlkIHlvdSByZWFsbHkgdHJ5IHRvIGRlY29kZSBhbiBleGFtcGxlIEpXVD8ifQ.ha6rxS3FXwkj5dOcBps1ji0z_CgBgID0eYPHnEtDOKg",
"expiry": 1633040000,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNjc3NDgwNDg3IiwiaXNzIjoiVHVyYm9Db3JlIiwidHlwZSI6ImF0IiwidWlkIjoiRGlkIHlvdSByZWFsbHkgdHJ5IHRvIGRlY29kZSBhbiBleGFtcGxlIEpXVD8ifQ.ha6rxS3FXwkj5dOcBps1ji0z_CgBgID0eYPHnEtDOKg",
"email_verified": true,
"metadata": "{\"role\": \"admin\", \"name\": \"John Doe\", \"age\": 21}"
}
Common Errors:
- INVALID_CREDENTIALS: The email or password is invalid
- USER_DISABLED: The user has been disabled by an administrator
POST /api/auth/user/create
You can create a user by sending a POST request to the /api/auth/user/create
endpoint.
Method: POST
Endpoint: /api/auth/user/create
Request Body:
Property Name | Type | Description |
---|---|---|
string | The email of the user | |
password | string | The password of the user |
login | boolean | Whether to login the user after signing up |
email_verified | boolean | Whether the user's email has been verified |
metadata | string | A JSON string to store additional metadata about the user |
Response Body:
Property Name | Type | Description |
---|---|---|
uid | string | The UID of the new user |
token | string | null | The JWT token of requested the user |
expiry | string | null | The date the token expires in UNIX epoch time |
refresh_token | string | null | A token used to get a new JWT token from TurboCore |
email_verified | boolean | null | Whether the user's email has been verified |
metadata | string | null | A JSON string to store additional metadata about the user |
Example responses:
Without login:
{
"uid": "710f7e29-4082-4421-b9b5-49f56a393832"
}
With login:
{
"uid": "710f7e29-4082-4421-b9b5-49f56a393832",
"token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNjc3NDgwNDg3IiwiaXNzIjoiVHVyYm9Db3JlIiwidHlwZSI6ImF0IiwidWlkIjoiRGlkIHlvdSByZWFsbHkgdHJ5IHRvIGRlY29kZSBhbiBleGFtcGxlIEpXVD8ifQ.ha6rxS3FXwkj5dOcBps1ji0z_CgBgID0eYPHnEtDOKg",
"expiry": 1633040000,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNjc3NDgwNDg3IiwiaXNzIjoiVHVyYm9Db3JlIiwidHlwZSI6ImF0IiwidWlkIjoiRGlkIHlvdSByZWFsbHkgdHJ5IHRvIGRlY29kZSBhbiBleGFtcGxlIEpXVD8ifQ.ha6rxS3FXwkj5dOcBps1ji0z_CgBgID0eYPHnEtDOKg",
"email_verified": true,
"metadata": "{\"role\": \"admin\", \"name\": \"John Doe\", \"age\": 21}"
}
Common Errors:
- EMAIL_ALREADY_IN_USE: The email is already in use
- INVALID_EMAIL: The email is invalid
- WEAK_PASSWORD: The password is too weak
POST /api/auth/user/refresh
You can refresh a user's JWT token by sending a POST request to the /api/auth/user/refresh
endpoint.
Method: POST
Endpoint: /api/auth/user/refresh
Request Body:
Property Name | Type | Description |
---|---|---|
refresh_token | string | The refresh token of the user |
Response Body:
Property Name | Type | Description |
---|---|---|
uid | string | The UID of the requested user |
access_token | string | The JWT token of requested the user |
refresh_token | string | A token used to get a new JWT token from TurboCore |
expiry | integer | The date the token expires in UNIX epoch time |
Example Response:
{
"uid": "710f7e29-4082-4421-b9b5-49f56a393832",
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNjc3NDgwNDg3IiwiaXNzIjoiVHVyYm9Db3JlIiwidHlwZSI6ImF0IiwidWlkIjoiRGlkIHlvdSByZWFsbHkgdHJ5IHRvIGRlY29kZSBhbiBleGFtcGxlIEpXVD8ifQ.ha6rxS3FXwkj5dOcBps1ji0z_CgBgID0eYPHnEtDOKg",
"expiry": 1633040000,
"refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOiIxNjc3NDgwNDg3IiwiaXNzIjoiVHVyYm9Db3JlIiwidHlwZSI6ImF0IiwidWlkIjoiRGlkIHlvdSByZWFsbHkgdHJ5IHRvIGRlY29kZSBhbiBleGFtcGxlIEpXVD8ifQ.ha6rxS3FXwkj5dOcBps1ji0z_CgBgID0eYPHnEtDOKg"
}
Common Errors:
- INVALID_REFRESH_TOKEN: The provided JWT could not be verified by the server
- EXPIRED_JWT: The provided JWT has already expired
POST /api/auth/user/logout π
You can revoke a user's refresh token by sending a POST request to the /api/auth/user/logout
endpoint. This has the effect of logging the user out. If a refresh token is not provided, then all the user's refresh token will be revoked, effectively logging the user out of all devices.
Method: POST
Endpoint: /api/auth/user/logout
Request Body:
Property Name | Type | Description |
---|---|---|
refresh_token | string | (Optional) The refresh token of the user |
Response Body: None
Common Errors:
- NOT_AUTHENTICATED: The
Authorization
header is missing or invalid
Warning: This endpoint does not revoke the user's access token, which expires after a maximum of 15 minutes.
POST /api/auth/magic-link
You can send a magic link to a user by sending a POST request to the /api/auth/magic-link endpoint. The user will be redirected to the URL specified in the next_url parameter after they sign in.
Method: POST
Endpoint: /api/auth/magic-link
Request Body:
Property Name | Type | Description |
---|---|---|
string | The email of the user | |
sign_up | boolean | Whether to create a new user if the user does not exist |
next_url | string | The URL to redirect the user to after they sign in |
Response Body: None
Next URL Parameters:
Property Name | Type | Description |
---|---|---|
uid | string | The UID of the user |
at | string | The JWT token of the user |
rt | string | A token used to get a new JWT token from TurboCore |
exp | integer | The date the token expires in UNIX epoch time |
Common Errors:
- INVALID_EMAIL: The email is invalid
- USER_NOT_FOUND: The user was not found
Once the user clicks the magic link, they will be redirected to the URL specified in the next_url parameter. The next_url parameter will be appended with the following query parameters: uid, at, rt, and exp as described in the table above.
POST /api/auth/user/verify-email π
You can verify a user's email by sending a POST request to the /api/auth/user/verify-email
endpoint. This will send a verification email to the user's email address.
Method: POST
Endpoint: /api/auth/user/verify-email
Request Body:
Property Name | Type | Description |
---|---|---|
next_url | string | The URL to redirect the user to after they verify their email |
Response Body: None
Common Errors:
- NOT_AUTHENTICATED: The
Authorization
header is missing or invalid - EMAIL_ALREADY_VERIFIED: The user's email is already verified
- USER_NOT_FOUND: The user was not found
- EMAIL_NOT_CONFIGURED: The server is not configured to send emails
PATCH /api/auth/user/change-password π
You can change a user's password by sending a PATCH request to the /api/auth/user/change-password
endpoint.
Method: PATCH
Endpoint: /api/auth/user/change-password
Request Body:
Property Name | Type | Description |
---|---|---|
old_password | string | The old password of the user or a reset password token |
new_password | string | The new password of the user |
Response Body: None
Common Errors:
- NOT_AUTHENTICATED: The
Authorization
header is missing or invalid - INVALID_PASSWORD: The old password is invalid
- WEAK_PASSWORD: The new password is too weak
POST /api/auth/reset-password
You can reset a user's password by sending a POST request to the /api/auth/reset-password
endpoint. This will send a password reset email to the user's email address. For security, this endpoint does not return an error if the email is not found.
Method: POST
Endpoint: /api/auth/reset-password
Request Body:
Property Name | Type | Description |
---|---|---|
string | The email of the user | |
reset_url | string | The URL where the user can reset their password |
Response Body: None
Reset URL Parameters:
Property Name | Type | Description |
---|---|---|
token | string | A token used to reset the user's password. Pass this token to /api/auth/user/change-password |
The reset_url parameter will be appended with a token that can be used to reset the user's password by sending a PATCH request to the /api/auth/user/change-password
endpoint.
PUT /api/auth/user π
You can update a user's email or metadata by sending a PUT request to the /api/auth/user
endpoint.
Method: PUT
Endpoint: /api/auth/user
Request Body:
Property Name | Type | Description |
---|---|---|
string | The new email of the user | |
metadata | string | A JSON string to store additional metadata about the user |
Response Body: None
Common Errors:
- NOT_AUTHENTICATED: The user is not signed in
- EMAIL_ALREADY_IN_USE: The email is already in use
- INVALID_EMAIL: The email is invalid
DELETE /api/auth/user π
You can delete a user by sending a DELETE request to the /api/auth/user
endpoint.
Method: DELETE
Endpoint: /api/auth/user
Request Body: None
Response Body: None
Common Errors:
- NOT_AUTHENTICATED: The
Authorization
header is missing or invalid