# User API
Stadium applications with Authentication mode *Email & Password* or *Single Sign-on* come with a REST API that can be used to remotely manage application users.
## Setup
Calling the application User API requires a key. Generate this key in the Stadium Application Manager (SAM) under the application's *User API* section.
Here you can also download an Open API definition file. When importing this file into Stadium, Linx or a number of other applications, a Web Service will be generated with all available User API operations and types.
## Operations
The API exposes the operations below
Replace the *\* placeholder in the URL's below with the key you generated for your application. Replace the *\* placeholder with the base url of your site (e.g. server.com/myapplication)
### Fetch All Users
Returns a Json object containing all users. Use a querystring parameter "email" to filter the results by email.
URL
```
https:///api/users?key=&email=@example.com
```
Method
```
GET
```
Example Response (application/json)
```json
[
{
"id": "2e718832-3669-43f3-8eae-75f30360c17d",
"email": "mike.carter23@example.com",
"name": "Mike Carter",
"username": "mike.carter23@example.com",
"isAdministrator": true,
"roles": [
"User",
"Developer"
],
"data": {}
},
{
"id": "d02123fd-730d-4c93-a9c9-e0ee4270e94d",
"email": "loretta.pearson50@example.com",
"name": "Loretta Pearson",
"username": "loretta.pearson50@example.com",
"isAdministrator": false,
"roles": [
"User",
"Team Leader"
],
"data": {}
}
]
```
NOTE: The *data* object is used in the Single Sign-On process by Stadium and is not available to API users.
### Fetch User
Returns a Json object containing the details of a specific user
The UserID is generated by Stadium and can be retrieved using the Fetch User API call
URL
```
https:///api/users/?key=
```
Method
```
GET
```
Example Response (application/json)
```json
{
"id": "d02123fd-730d-4c93-a9c9-e0ee4270e94d",
"email": "loretta.pearson50@example.com",
"name": "Loretta Pearson",
"username": "loretta.pearson50@example.com",
"isAdministrator": false,
"roles": [
"User",
"Team Leader"
],
"data": {}
}
```
NOTE: The *data* object is used in the Single Sign-On process by Stadium and is not available to API users.
### Add User
Creates a new user record
URL
```
https:///api/users?key=
```
Method
```
POST
```
Content Type
```
application/json
```
Body (example)
```json
{
"email": "",
"name": "",
"password": "",
"roles": ["", ""],
"isAdministrator": true
}
```
Example Response (application/json)
```json
{
"userID": "efd1251c-d986-4d52-bf61-38b7b384958b"
}
```
### Update User
Updates an existing user record
The UserID is generated by Stadium and can be retrieved using the Fetch Users API call
URL
```
https:///api/users/?key=
```
Method
```
PUT
```
Content Type
```
application/json
```
Body - all fields are optional (example)
```json
{
"email": "",
"name": "",
"password": "",
"roles": ["", ""],
"isAdministrator": true
}
```
### Delete User
Deletes an existing user
The UserID is generated by Stadium and can be retrieved using the Fetch Users API call
URL
```
https:///api/users/?key=
```
Method
```
DELETE
```
### Fetch Roles
Returns a Json object containing all available roles
URL
```
https:///api/roles?key=
```
Method
```
GET
```
Example Response (application/json)
```json
[ "Developer", "Team Leader", "User" ]
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.stadium.software/how-it-works/user-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.