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.

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:

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:

Response Body:

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:

Response Body:

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:

Response Body:

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:

Response Body: None

Common Errors:

• NOT_AUTHENTICATED: The Authorization header is missing or invalid

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:

Response Body: None

Next URL Parameters:

Common Errors:

• INVALID_EMAIL: The email is invalid
• USER_NOT_FOUND: The user was not found

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:

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:

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:

Response Body: None

Reset URL Parameters:

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:

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