diff --git a/_authentication.md b/_authentication.md index ca23035..5f2af9f 100644 --- a/_authentication.md +++ b/_authentication.md @@ -1,37 +1,85 @@ # Authentication -Uphold is an OAuth 2.0 compliant service. +Uphold is an [OAuth 2.0](https://tools.ietf.org/html/rfc6749) compliant service. -Partners looking to integrate with our API must [register an application](#registering-an-application). Applications that implement a user-facing web interface, to provide custom functionality for multiple Uphold users, should use the [Web Application Flow](#web-application-flow). Applications that implement a backend interface for a corporate partner (and therefore represent an Uphold user themselves) should use the [Client Credentials Flow](#client-credentials-flow). +It is mandatory that partners with **Business Accounts** looking to integrate with this API **must request** Uphold to [register an application](https://support.uphold.com/hc/en-us/articles/217210266) and access roles. -## Web Application Flow +![register](assets/register.png) -Ideal for web applications that wish to retrieve information about a user's Uphold account or take actions on their behalf. +## Production/Sandbox Endpoints -### Step 1 - Authorization +- **Production** - Site/API + - `https://uphold.com` + - `https://api-uphold.com` +- **Sandbox** - Site/API + - `https://sandbox.uphold.com` + - `https://api-sandbox.com` -The authenticating web application should redirect users to the following URL: +Please use the correct **endpoint** for your scenario. For documentation proposes we are going to use the sandbox Urls. -`https://uphold.com/authorize/` -Or for sandbox applications: -`https://sandbox.uphold.com/authorize/` +## Web application flow -Supported query parameters: +Ideal for Partner web/mobile applications that wish to retrieve information about a user's Uphold account or take actions on their behalf. + +### Use case + +Web/Mobile application that implement a user-facing web interface, to provide custom functionality for multiple Uphold users. This Auth-flow is used by Partners looking to integrate with Uphold API. + +[Uphold javascript web application authentication sample](https://github.com/uphold/rest-api-examples/rest-api/javascript/authentication/web-application-flow) + +### Workflow after Uphold request approval + +#### Step 1 - Authorization request! + +Partner **application** should redirect users to the following URL: + +`https://sandbox.uphold.com/authorize/` + +Parameters: Parameter | Required | Description --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- intention | no | Unauthenticated users will be redirected to the `login` page, this behavior can be changed by sending `signup` as the `intention` value. -scope | yes | Permissions to request from the user. -state | yes | An unguessable, cryptographically secure random string used to protect against cross-site request forgery attacks. +scope | **yes** | Permissions to request from the user. +state | **yes** | An unguessable, cryptographically secure random string used to protect against cross-site request forgery attacks. + +Example: + +`https://sandbox.uphold.com/authorize/MY_CLIENT_ID?scope=user:read&state=MY_UNGUESSABLE_STATE` + +![Authorization](assets/authorization.png) + +If everything goes well the Uphold API executes a callback URL **previously** defined by the Partner after Uphold **application/roles** request approval. + +![flow](assets/flow.png) + +#### Step 2 - Requesting an access Token + +If the user accepts your request, Uphold will redirect the user back to the Partner callback URL with a temporary `code` and the previously provided `state`, _as is_. + +This temporary `code` is valid has a duration of **5 minutes** and **can only be used once**. -### Step 2 - Requesting a Token +The Partner application is **now** responsible for ensuring that the `state` matches the value previously provided, thus preventing a malicious third-party from forging this request. -> Exchanging the `code` for a `token`: +**Finally**, you may exchange this `code` for an `access token` using the following endpoint: + +`POST https://api-sandbox.uphold.com/oauth2/token` + +Parameters: + +| Parameter | Required | Description | +| ------------- | -------- | ------------------------------------------------------------ | +| client_id | **yes** | The application's *clientId*. Please use HTTP Basic Authentication when possible. | +| client_secret | **yes** | The application's *clientSecret*. Please use HTTP Basic Authentication when possible. | +| code | **yes** | The code acquired in step 1. | +| grant_type | **yes** | Must be set to *'authorization_code'*. | + +> Here is a curl example to request exchanging the `code` for a `token`: ```bash -curl https://api.uphold.com/oauth2/token \ +curl https://api-sandbox.uphold.com/oauth2/token \ -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u : \ @@ -47,153 +95,106 @@ curl https://api.uphold.com/oauth2/token \ } ``` -If the user accepts your request, Uphold will redirect the user back to your site with a temporary `code` and the previously provided `state`, _as is_. - -This temporary `code` is valid for a duration of **5 minutes** and **can only be used once**. - -Your application is responsible for ensuring that the `state` matches the value previously provided, thus preventing a malicious third-party from forging this request. - -You may then exchange this `code` for an `access token` using the following endpoint: - -`POST https://api.uphold.com/oauth2/token` - -Or for sandbox applications: - -`https://api-sandbox.uphold.com/oauth2/token` - -Supported parameters: - -Parameter | Required | Description -------------- | -------- | ------------------------------------------------------------------------------------- -client_id | yes | The application's *clientId*. Please use HTTP Basic Authentication when possible. -client_secret | yes | The application's *clientSecret*. Please use HTTP Basic Authentication when possible. -code | yes | The code acquired in step 1. -grant_type | yes | Must be set to *'authorization_code'*. - +Once you have obtained an access token you may call any protected API method on behalf of the user using the "Authorization" HTTP header in the format: -### Step 3 - Using the Access Token +`Authorization: Bearer ` + +#### Step 3 - Using the access token to get my cards + +The Partner application can now use the provided **token** to query other protected endpoints of Uphold API. > Request using the 'Authorization' header: ```bash -curl https://api.uphold.com/v0/me/cards \ +curl https://api-sandbox.uphold.com/v0/me/cards \ -H "Authorization: Bearer " ``` -Once you have obtained an access token you may call any protected API method on behalf of the user using the "Authorization" HTTP header in the format: -`Authorization: Bearer ` - +For **business usage only**. Partners may choose to use client credentials authentication, this requires manual approval from Uphold with a **particular custom role approval**. -## Client Credentials Flow +### Use case -Ideal for backend integrations that do not require access to other Uphold user accounts. +Ideal for backend integrations that do not require access to **other** Uphold user accounts. -For **business usage only** you may choose to use client credentials authentication. This requires manual approval from Uphold. +[Uphold javascript client credential authentication sample](https://github.com/uphold/rest-api-examples/rest-api/javascript/authentication/client-credential-flow) -### Creating a Token +#### Step 1 - Creating a token -> To create a client credentials token, execute the following command (make sure the application is set to use client credentials and not authorization code): +> To create a client credentials token, execute the following command (make sure the application is set to use client credentials and not authorization code): ```bash -curl https://api.uphold.com/oauth2/token \ +curl https://api-sandbox.uphold.com/oauth2/token \ -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -u : \ -d 'grant_type=client_credentials' ``` -To create a client credentials token you may use the following endpoint: - -`POST https://api.uphold.com/oauth2/token` - -Supported parameters: +Parameters: Parameter | Required | Description ------------- | -------- | ------------------------------------------------------------------------------------- -client_id | yes | The application's *clientId*. Please use HTTP Basic Authentication when possible. -client_secret | yes | The application's *clientSecret*. Please use HTTP Basic Authentication when possible. -grant_type | yes | Must be set to *'client_credentials'*. +client_id | **yes** | The application's *clientId*. Please use HTTP Basic Authentication when possible. +client_secret | **yes** | The application's *clientSecret*. Please use HTTP Basic Authentication when possible. +grant_type | **yes** | Must be set to ***'client_credentials'***. +Once you have obtained an access token you may call any protected API method on behalf of the user using the "Authorization" HTTP header in the format: + +`Authorization: Bearer ` -### Using the Token +#### Step 2 - Using the token to get my cards + +Finally, the Partner application can now use the provided **token** to query other protected endpoints of Uphold API. > Request using the 'Authorization header': ```bash -curl https://api.uphold.com/v0/me/cards \ +curl https://api-sandbox.uphold.com/v0/me/cards \ -H "Authorization: Bearer " ``` -Once you have obtained a client credentials token you may call any protected API method on behalf of the user account owner of the application using the "Authorization" HTTP header in the format: - -`Authorization: Bearer ` - ## Personal Access Tokens (PAT) -Ideal for scripts, automated tools and command-line programs which remain under your control. - -For **personal usage only** you may choose to use a PAT. This token establishes who you are, provides full access to your user account and bypasses Two Factor Authentication, if enabled. For this reason it should be treated just like your email/password combination, i.e. remain secret and never shared with third parties. PATs can be issued and revoked individually. +For **personal usage only** you may choose to use a **PAT**. This token establishes who you are, provides full access to your user account and bypasses Two Factor Authentication, if enabled. For this reason it should be treated just like your email/password combination, i.e. remain secret and never shared with third parties. PATs can be issued and revoked individually. -### Listing PATs +### Use case -> To list active Personal Access Tokens, execute the following command: - -```bash -curl https://api.uphold.com/v0/me/tokens \ - -H "Authorization: Bearer " -``` - -> The above command returns the following JSON: - -```json -[ - { - "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634", - "description": "token 1" - }, - { - "id": "b97bb994-6e24-4a89-b653-e0a6d0bcf635", - "description": "token 2" - } -] -``` - -To list Personal Access Tokens you may use the following endpoint: +Ideal for scripts, automated tools and command-line programs which remain under your control. -`GET https://api.uphold.com/v0/me/tokens` +[Uphold javascript PAT authentication sample](https://github.com/uphold/rest-api-examples/rest-api/javascript/authentication/client-credential-pat) -### Creating a PAT +#### Step 1 - Creating a PAT > To create a Personal Access Token, execute the following command: ```bash -curl https://api.uphold.com/v0/me/tokens \ +curl https://api-sandbox.uphold.com/v0/me/tokens \ -X POST \ - -H "Authorization: Bearer " \ + -H "Authorization: Basic " \ -H "Content-Type: application/json" \ -H "OTP-Method-Id: " \ -H "OTP-Token: " \ -d '{ "description": "My command line script" }' ``` +**IMPORTANT** + +1. Uses **Basic Authentication** to create the PAT. +2. **username:password** combination should be encoded with **Base64** +3. **OTP-Method-ID** and **OTP-Token** are mandatory if the account has 2FA enabled. + > The above command returns the following JSON: ```json @@ -204,49 +205,70 @@ curl https://api.uphold.com/v0/me/tokens \ } ``` -To create a Personal Access Token you may use the following endpoint: +Parameters: -`POST https://api.uphold.com/v0/me/tokens` +| Parameter | Required | Description | +| ----------- | -------- | ----------------------------------------- | +| description | **yes** | A human-readable description of this PAT. | -Supported parameters: +#### Step 2 - Managing PAT -Parameter | Required | Description ------------ | -------- | ----------------------------------------- -description | yes | A human-readable description of this PAT. +##### Listing PAT's - - +> To list active Personal Access Tokens, execute the following command: + +```bash +curl https://api-sandbox.uphold.com/v0/me/tokens \ + -H "Authorization: Bearer " +``` + +> The above command returns the following JSON: + +```json +[ + { + "id": "a97bb994-6e24-4a89-b653-e0a6d0bcf634", + "description": "token 1" + }, + { + "id": "b97bb994-6e24-4a89-b653-e0a6d0bcf635", + "description": "token 2" + } +] +``` + +To list Personal Access Tokens you may use the following endpoint: + +`GET https://api-sandbox.uphold.com/v0/me/tokens` -### Revoking a PAT +##### Revoking a PAT > To revoke a Personal Access Token, execute the following command: ```bash -curl https://api.uphold.com/v0/me/tokens/:token \ +curl https://api-sandbox.uphold.com/v0/me/tokens/:token \ -X DELETE \ -H "Authorization: Bearer " ``` To revoke a Personal Access Token you may use the following endpoint: -`DELETE https://api.uphold.com/v0/me/tokens/:token` +`DELETE https://api-sandbox.uphold.com/v0/me/tokens/:token` -Supported parameters: +Parameters: Parameter | Required | Description --------- | -------- | --------------------------- -token | yes | The PAT you wish to revoke. +token | **yes** | The PAT you wish to revoke. -### Using a PAT +#### Step 3 - Using a PAT to get my data + +As stated, after "having" a PAT token there is no need to pass the 2FA headers if this security extra layer is active. > Example of using a personal access token to make requests to our API: ```bash -curl https://api.uphold.com/v0/me \ +curl https://api-sandbox.uphold.com/v0/me \ -H "Authorization: Bearer " ``` @@ -254,18 +276,35 @@ A PAT may be used for authenticating a request via the OAuth scheme. The `` should be set as the `accessToken` received during creation. + + +## Security Notice (Web Flow/Client Credential/PAT)- Token Header + +Once you have obtained a **token** you may call any protected API method using the "Authorization" HTTP header in the format: + +`Authorization: Bearer ` + +