User Management APIs
You can use the 1up FHIR API User Management endpoints to create individual users in the 1up FHIR Server and manage their user permissions.
User Management API Reference¶
When you connect to the User Management endpoints, you must send the client_id and client_secret parameters for the user in the request header.
Get Users¶
GET https://api.1up.health/user-management/v1/user
Get the list of all the users that exist inside your 1up Developer Application.
You can filter by user.
Parameters
| Authorization |
string |
This endpoint receives authentication requests as an HTTP authentication header with a Bearer token. |
Responses
| 200
|
User successfully retrieved.¶
1
2
3
4
5
6
7
{
"oneup_user_id" : "string",
"app_user_id" : "string",
// Indicates whether the user is active or not
"active" : "boolean",
},
|
| 400
|
|
Create User¶
POST https://api.1up.health/user-management/v1/user
This request creates a user with the attributes that you specify in the request body.
If the user already exists in the 1up FHIR Server, the request won't fail, but you'll receive the following error.
this user already exists
Parameters
| Authorization |
string |
This endpoint receives authentication requests as an HTTP authentication header with a Bearer token. |
| app_user_id |
string |
Self-defined user name. |
|
client_id
|
string
|
One of two API keys generated for a new application.
|
|
client_secret
|
string
|
One of two API keys generated for a new application.
|
Responses
| 200
|
User successfully retrieved.¶
1
2
3
4
5
6
7
{
"success" : "boolean",
"code" : "string",
"app_user_id" : "string",
"oneup_user_id" : "string",
"active" : "boolean",
}
|
| 404
|
|
Update User¶
PUT https://api.1up.health/user-management/v1/user
You can use the Update User endpoint to modify an existing user object.
You can modify only the app_user_id. The oneup_user_id can’t be changed.
Parameters
|
client_id
|
string
|
One of two API keys generated for your application.
|
|
client_secret
|
string
|
One of two API keys generated for your application.
|
| app_id_user |
string |
Self-defined user name. |
|
oneup_user_id
|
string
|
System-generated user ID based on the user name.
|
Responses
Grant Permissions to a User¶
PUT https://api.1up.health/dstu2/Patient/patientid/_permission/oneup_user_id_to_gain_access
When you make a request to the 1up FHIR API with a user's access_token, the resources returned include only the resources that the user has permission to view. You can also use this endpoint to enable patients to allow other users to get access to the records that they authorize access to.
Parameters
|
Authorization
|
string
|
This access token is owned by the user who owns the resource.
This endpoint receives authentication in the form of an HTTP authentication header Bearer token.
|
Responses
Revoke User Permissions¶
DELETE https://api.1up.health/dstu2/Patient/patientid/_permission/oneup_user_id_to_lose_access
This endpoint allows you to remove permissions that have been granted to users to see another user's FHIR® resources.
Parameters
| Authorization |
string |
This endpoint receives authentication requests as an HTTP authentication header with a Bearer token. |
Responses
Use the User Management API¶
User Management is central to 1upHealth's APIs. You can use the User Management endpoints to create users, and manage their permissions and data. With the User Management endpoint, you can organize patient data under specific patients. This means that a patient's data that's authorized from multiple sources can be stored under a single user, which makes their patient data easier to use in applications, such as Patient Connect.
Before You Begin¶
Before you can use the 1up FHIR API User Management endpoint, you must get the necessary OAuth client keys for the 1up FHIR API, create a developer account, and get access to the 1upHealth Developer Console.
Rate Limits¶
You can make a maximum of 300 calls in an hour to the User Management endpoint. If you make more than 300 calls, you’ll receive an HTTP 429 error, which specifies that you sent too many requests.
Create a User¶
To create a user, your applications can send the following request. Each response contains the new user's oneup_user_id, access_token, refresh_token, and app_user_id. The app_user_id identifies the user in your application to help you manage the list of users between the 1up FHIR API and your own user management system.
Create user request¶
1
2
3
4
5
$ curl -X POST "https://api.1up.health/user-management/v1/user" \
-H "client_id: clientidclientidclientid" \
-H "client_secret: clientsecretclientsecret" \
-d "app_user_id=myappsuserid"
Example response¶
1
2
3
4
5
6
7
{
success: true,
code: 'accesscodeaccesscodeaccesscode',
oneup_user_id: 251,
app_user_id: '1499270216467',
active: true
}
The code variable in the response is the OAuth 2.0 access code. You must exchange that to get the OAuth 2.0 access token by following the steps to get an OAuth 2.0 token. The access_token and refresh_token are required to access to user data.
Make sure to use a HIPAA-compliant method of transmission and storage to secure your access_token and refresh_token, and all other patient data.
The auth token expires after 7200 seconds (2 hours). To refresh the token, complete the OAuth 2.0 token refresh process.
Generate an access token request¶
1
2
3
4
5
curl -X POST "https://auth.1up.health/oauth2/token" \
-d "code=accesscodeaccesscodeaccesscode" \
-d "client_id=clientidclientidclientid" \
-d "client_secret=clientsecretclientsecret" \
-d "grant_type=authorization_code"
Example response¶
1
2
3
4
5
6
7
{
"access_token" => "accesstokenaccesstokenaccesstoken",
"token_type" =>"Bearer",
"expires_in" => 7200,
"refresh_token" => "refreshtokenrefreshtokenrefreshtoken",
"scope" => "user"
}
If you need a new authorization code for a user that you already created in the 1up FHIR Server, you can use the following method to make a request.
Get a new authorization code for an existing user¶
1
2
3
4
curl -X POST "https://api.1up.health/user-management/v1/user/auth-code" \
-H "client_id: clientidclientidclientid" \
-H "client_secret: clientsecretclientsecret" \
-d "app_user_id=myappuserid"
Review the User List¶
To review the list of all users, you can paginate through the users from the User Management endpoint.
To run a query for individual users, you can add the oneup_user_id and app_user_id parameters to your request.
Example query request for an individual user¶
1
2
3
4
5
curl -X GET "https://api.1up.health/user-management/v1/user" \
-H "client_id: clientidclientidclientid" \
-H "client_secret: clientsecretclientsecret" \
-d "oneup_user_id=123" \
-d "app_user_id=myappuserid"
Update Users¶
To change the app_user_id, you can run the following command.
Update a user request¶
1
2
3
4
5
curl -X PUT "https://api.1up.health/user-management/v1/user" \
-H "client_id: clientidclientidclientid" \
-H "client_secret: clientsecretclientsecret" \
-d "oneup_user_id=123" \
-d "app_user_id=newappuserid"
You can modify only the app_user_id. The oneup_user_id is automatically assigned to the user and can’t be changed.
Manage Patient Data for a User¶
You can create any FHIR® resource and associate it with a user.
For example, you can create a Patient resource, and give the user a name, gender, or age. To do this, you can include the user's auth_token in a request when you create or update a FHIR resource.
