Hydra is a zero-config API boilerplate with Laravel Sanctum and comes with excellent user and role management API out of the box. Start your next big API project with Hydra, focus on building business logic, and save countless hours of writing boring user and role management API again and again.
Please note that the default admin user is **admin@hydra.project** and default password is **hydra**. You should create a new admin user before deploying to production and delete this default admin user. You can do that using available Hydra user management API, or using any DB management tool.
## Default Roles
Hydra comes with these `super-admin`,`admin`,`editor`,`customer` &`user` roles out of the box. For details, open the roles table after database seeding, or simply open laravel tinker and experiment with `Role` model
Let's have a look at what Hydra has to offer. Before experimenting with the following API endpoints, run your Hydra project using `php artisan serve` command. For the next part of this documentation, we assumed that Hydra is listening at http://localhost:8000
### User Registration
You can make an `HTTP POST` call to the following endpoint to create/register a new user. newly created user will have the `user` role by default.
```shell
http://localhost:8000/api/users
```
**API Payload & Response**
You can send a Form Multipart payload or a JSON payload like this
```json
{
"name":"Hydra User",
"email":"user@hydra.project",
"passsword":"Surprisingly A Good Password"
}
```
Voila! your user has been created and is now ready to login!
To list the users, make an `HTTP GET` call to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call.
```shell
http://localhost:8000/api/users
```
**API Payload & Response**
No payload required for this call.
You will get a JSON response with all users available in your project.
```json
[
{
"id": 1,
"name": "Hydra Admin",
"email": "admin@hydra.project"
},
{
"id": 2,
"name": "Test User",
"email": "test@hydra.project"
},
]
```
For any unsuccsesful attempt or wrong token, you will receive a 401 error response.
To update an existing user, make a `HTTP PUT` request to the following route. Replace {userid} with actual user id. You must includ a Bearer token obtained from User/Admin authentication. A bearer admin token can update any user. A bearer user token can only update the authenticated user by this token.
```shell
http://localhost:8000/api/users/{userid}
```
For example to update the user with id 2, use this endpoint `http://localhost:8000/api/users/3`
**API Payload & Response**
You can include either `name` or `email`, or both in a URL Encoded Form Data or JSON payload, just like this
For any unsuccsesful attempt with invalid `user id`, you will receive a 404 not found error response. For example when you are trying to delete a non existing user with id 16, you will receive the following response.
```json
{
"error": 1,
"message": "No query results for model [App\\Models\\User] 16"
For example to delete the user with id 2, use this endpoint `http://localhost:8000/api/users/2`
**API Payload & Response**
No payload is required for this call.
You will get a JSON response with user token. You need this user token for making any call to other routes protected by user ability.
```json
{
"error": 0,
"message": "user deleted"
}
```
For any unsuccsesful attempt with invalid token, you will receive a 401 error response.
```json
{
"error": 1,
"message": "invalid credentials"
}
```
For any unsuccsesful attempt with invalid `user id`, you will receive a 404 not found error response. For example when you are trying to delete a non existing user with id 16, you will receive the following response.
```json
{
"error": 1,
"message": "No query results for model [App\\Models\\User] 16"
To list the roles, make an `HTTP GET` call to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call.
```shell
http://localhost:8000/api/roles
```
**API Payload & Response**
No payload required for this call.
You will get a JSON response with all the roles available in your project.
```json
[
{
"id": 1,
"name": "Administrator",
"slug": "admin"
},
{
"id": 2,
"name": "User",
"slug": "user"
},
{
"id": 3,
"name": "Customer",
"slug": "customer"
},
{
"id": 4,
"name": "Editor",
"slug": "editor"
},
{
"id": 5,
"name": "All",
"slug": "*"
},
{
"id": 6,
"name": "Super Admin",
"slug": "super-admin"
}
]
```
For any unsuccsesful attempt or wrong token, you will receive a 401 error response.
```json
{
"message": "Unauthenticated."
}
```
### Add a New Role (Admin Ability Required)
To list the roles, make an `HTTP POST` call to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call.
```shell
http://localhost:8000/api/roles
```
**API Payload & Response**
You need to supply title of the role as `name`, role `slug` in your payload as Multipart Form or JSON data
```json
{
"name":"Manager",
"slug":"manager"
}
```
For successful execution, you will get a JSON response with this newly created role.
```json
{
"name": "Manager",
"slug": "manager",
"id": 7
}
```
If this role `slug` already exists, you will get a 409 error message like this
```json
{
"error": 1,
"message": "role already exists"
}
```
For any unsuccsesful attempt or wrong token, you will receive a 401 error response.
To update a role, make an `HTTP PUT` or `HTTP PATCH` request to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call.
For example to update the Customer role, use this endpoint `http://localhost:8000/api/roles/3`
**API Payload & Response**
You need to supply title of the role as `name`, and/or role `slug` in your payload as Multipart Form or JSON data
```json
{
"name":"Product Customer",
"slug":"product-customer"
}
```
For successful execution, you will get a JSON response with this updated role.
```json
{
"id": 3,
"name": "Product Customer",
"slug": "product-customer"
}
```
Please note that you cannot change a `super-admin` or `admin` role slug because many API routes in Hydra exclusively require this role to function properly.
For any unsuccsesful attempt or wrong token, you will receive a 401 error response.
To delete a role, make an `HTTP DELETE` request to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call.
```shell
http://localhost:8000/api/roles/{roleid}
```
For example to delete the Customer role, use this endpoint `http://localhost:8000/api/roles/3`
**API Payload & Response**
No payload required for this endpoint.
For successful execution, you will get a JSON response with this updated role.
```json
{
"error": 0,
"message": "role has been deleted"
}
```
Please note that you cannot delete the `admin` role because many API routes in Hydra exclusively require this role to function properly.
If you try to delete the admin role you will receive the following 422 error response
```json
{
"error": 1,
"message": "you cannot delete this role"
}
```
For any unsuccsesful attempt or wrong token, you will receive a 401 error response.
### List Available Roles of a User (Admin Ability Required)
To list all available roles for a user, make an `HTTP GET` request to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call. Replace {userid} with an actual user id
```shell
http://localhost:8000/api/users/{userid}/roles
```
For example to get all roles assigned to the user with id 2, use this endpoint `http://localhost:8000/api/users/2/roles`
For any unsuccsesful attempt or wrong token, you will receive a 401 error response.
```json
{
"message": "Unauthenticated."
}
```
### Assign a Role to a User (Admin Ability Required)
To assign a role to a user, make an `HTTP POST` request to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call. Replace {userid} with an actual user id
### Delete a Role from a User (Admin Ability Required)
To delete a role from a user, make an `HTTP DELETE` request to the following route, with Admin Token obtained from Admin Login. Add this token as a standard `Bearer Token` to your API call. Replace `{userid}` with an actual user id, and `{role}` with an actual role id
When a new user is created, the `user` role is aassigned to them. To change this behavior, open your `.env` file and set the value of `DEFAULT_ROLE_ID` to any existing role id and newly created users will have that role by default. For example, if you want your new users to have a `customer` role, set `DEFAULT_ROLE_ID=3` in your `.env` file.
When a user authenticates, Hydra doesn't invalidate the previously issued access token. So, all access tokens including the newly created token will remain balid. If you want to change this behavior and delete all previous tokens when a user authenticates, set `DELETE_PREVIOUS_ACCESS_TOKENS_ON_LOGIN` to `true` in your `.env` file. The value of `DELETE_PREVIOUS_ACCESS_TOKENS_ON_LOGIN` is set to `false` by default.
