Authentication & Authorization APIs

You can use 1up Authentication & Authorization APIs to authenticate and authorize access to FHIR® data on the 1up FHIR Server though OAuth 2.0 and 1up‘s users.

Authentication & Authorization API Reference

To authenticate to the 1up FHIR Server and use the other API endpoints to manage users and data, you must generate an authorization code that you can exchange for an access token.

POST   https://api.1up.health/user-management/v1/user/auth-code

A backend app can use this endpoint to get a new authorization code for a user. Note that this endpoint should not be called in a browser context because it would require exposing your app's secret key to users. The code received expires in 2 hours (7200 seconds).

Parameters

Body    
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 
{
  "client_id" : "string",
  "app_user_id" : "string",
  "client_secret" : "string",
}
404

Returns an authorization code that you can exchange for an access token and refresh token.

{
  "success" : "boolean",
  "code" : "string",
  "oneup_user_id" : "string",
  "app_user_id" : "string",
  "active" : "boolean",
}

POST  https://auth.1up.health/oauth2/token

A back-end app can use this endpoint to exchange the authorization code for these tokens: access_token, refresh_token, and id_token. The id_token is only returned if you include the openid scope when you request the code.

Don’t call this endpoint in a browser because it requires exposing your applications secret key to users.

Parameters

Body    
code string Access code is exchanged for the bearer token.

grant_type

string

authorization_code

client_id

string

1/2 API keys generated in creating a new application.

secret

string

1/2 API keys generated in creating a new application.

Responses

200

Returns an access_token, refresh_token, and optional id_token.

The access_token expires in two hours (7200 seconds). To get a new access_token, use the refresh_token or generate a new authorization code.

{
  "client_id" : "string",
  "app_user_id" : "string",
  "client_secret" : "string",
}

POSThttps://auth.1up.health/oauth2/token

A back-end application can use this endpoint to exchange the refresh_token for a user for an access_token, refresh_token, and id_token.

Parameters

Body    
refresh_token string The refresh token generated for your application.

grant_type

string

refresh_token

client_id

string

API key generated for your application.

client_secret

string

API key generated for your application.

Responses

200

Returns an access_token, refresh_token, and optional id_token.

The access_token expires in two hours (7200 seconds). To get a new access_token , use the refresh_token or generate a new authorization code. 

{
  "refresh_token" : "string",
  "token_type" : "string",
  "access_token" : "string",
  "expires_in" : "integer",
  "scope" : "string",
  "id_token" : "string",
}

GET  https://api.1up.health/:fhirApiEndpoint

An application can make a request to certain 1upHealth APIs with a bearer token which was created from executing the token endpoint above. This access token is safe to sit on the client side because its scope is limited to the user accessing it. However client secrets used to get the access token should remain on the server side.

Parameters

Path    
fhirApiEndpoint string The 1upHealth API endpoint path: /r4, /stu3, or /dsut2.
Header    
Authorization string

The type of authorization token and value.

Example — `Bearer: xyz`

Responses

200

 

GET  https://api.1up.health/:fhirApiEndpoint

An application can make a request to certain 1up API with the client ID and client secret (1up user credentials) without getting a user-specific access token. This method should be reserved to system level access and not be revealed to end users on client side code.

Parameters

Path    
fhirApiEndpoint string The 1upHealth API endpoint path: /r4, /stu3, or /dsut2.
Header    
x-oneup-user-id string

The 1up user ID which should be accessed during the request. The oneup_user_id is a numeric auto assigned value created for every user, NOT the app_user_id. For GET requests only, a special case of setting this value to "client" will return all data for all your client's users

client_secret

string

1up application Client ID

client_id

string

1up application Client Secret

Responses

200

 

GET  https://api.1up.health/:fhirApiEndpoint

An application can make a request to certain 1upHealth APIs with the client ID and client secret without getting a user specific access token. This method should be reserved to system level access and not be revealed to end users on client side code.

Parameters

Path    
fhirApiEndpoint string The 1upHealth API endpoint path: /r4, /stu3, or /dsut2.
Header    
x-app-user-id string

The 1up user ID which should be accessed during the request. The oneup_user_id is a numeric auto assigned value created for every user, NOT the app_user_id. For GET requests only, a special case of setting this value to "client" will return all data for all your client's users

client_secret

string

1up application Client ID

client_id

string

1up application Client Secret

Responses

200

 

Use the Authentication & Authorization API

You can use the 1up Authentication & Authorization API to make authorized and authenticated connections to 1upHealth APIs.

Generate a New User Authorization Code

1upHealth use the OAuth 2.0 process, which entails generating an authentication code and exchanging it for an access token. Generate the authentication code by requesting the user management API with the client_id, client_secret, and oneup_user_id or app_user_id.

curl -X POST "https://api.1up.health/user-management/v1/user/auth-code" \                        
     -d "client_id=clientidclientidclientid" \
     -d "client_secret=clientsecretclientsecret" \
     -d "app_user_id=myappsuserid"
{
     "success": true,
     "code": "75b74e18e1504fde865f40f4308317b2",
     "oneup_user_id": 62198,
     "app_user_id": "akuafo100",
     "active": true
}

Get an Access Token

After you get an authorization code, you can exchange it for an access token. You can use the access token to connect to 1up APIs with these parameters: client_id, client_secret, grant_type=token, and app_user_id.

curl -X POST "https://auth.1up.health/oauth2/token" \
                        -d "client_id=clientidclientidclientid" \
                        -d "client_secret=clientsecretclientsecret" \
                        -d "code=codecodecodecodecodecode" \
                    -d "grant_type=authorization_code"
{
                        "access_token": "xxxxxxxxxx",
                        "token_type": "Bearer",
                        "expires_in": 7199,
                        "refresh_token": "yyyyyyyyyy",
                        "scope": "user/*.*"
                    }

To test the access token, you can either authorize data from a provider or create a FHIR resource using the token. You can then call the Patient resource to get the existing data for this resource.

Query All Users

You can make a request across all your users using client-based authentication. This requires the client_id, client_secret, and x-oneup-user-id headers.

To submit a query for data for all of your client’s users, set the x-oneup-user-id string to client.

curl -XGET 'https://api.1up.health/r4/Patient' \
                        -H 'client_id: clientidclientidclientid' \
                        -H 'client_secret: clientsecretclientsecret' \
                    -H 'x-oneup-user-id: client'

The response is a valid FHIR response with data from all the users created under this client.

{
                        "resourceType": "Bundle",
                        "type": "searchset",
                        "total": 20800,
                        "entry": [
                        { ... },
                        { ... },
                        { ... },
                        ]
                        }