Authorization

OAuth Authorization Code flow

This flow is intended for clients and integrations which would allow usage of the SSO + 2FA UI (providing the same experience for end users as the official RushFiles / branded clients). For this kind of integration please contact RushFiles support.

OAuth Resource Owner Password Credentials flow

For Clients and Integrations that have their own Login UI or cannot use the system browser or an embedded browser to display the SSO + 2FA UI, the solution is to use the Resource Owner Password Credentials flow.
Follow the steps below to obtain JWTs (JSON Web Tokens). The examples shown use the cURL command line tool to perform HTTP requests.
If you have questions about which token endpoint or client credentials to use, please contact RushFiles support.

1) Obtaining an access token

First you need to obtain the access_token from the authorization server.

If your RushFiles installation is configured to use the main authority, or you want users across any RushFiles installation to use your integration, the authority server token endpoint is https://auth.rushfiles.com/connect/token.
If your RushFiles installation is configured to use only the local authority, or you want to allow access only for users from your installation, the authority server token endpoint is https://domainauth.yourdomain/connect/token.

You need to make an HTTP POST request with the following:

URL of token endpoint - for development please use https://auth-test.rushfiles.com/connect/token
Authorization Header - Basic containing the client credentials consisting of a client_id and a client_secret. Required when client credentials not sent in body.
Content-Type Header - application/x-www-form-urlencoded
Request Body - must contain grant_type=password, username, password and scope. If not using Authorization header, must contain client_id and client_secret

Example POST request for obtaining the access_token with client credentials in Authorization Header:

curl -X POST 
-H "Content-Type: application/x-www-form-urlencoded" 
-H "Authorization: Basic RXhhbXBsZUNsaWVudElkOkV4YW1wbGVTZWNyZXQ=" 
-d "grant_type=password&username=developer@rushfiles.com&password=userPassword@&scope=openid profile domain_api offline_access" 
https://auth-test.rushfiles.com/connect/token

In the example shown above, the client credentials used are ExampleClientId:ExampleSecret, which converted to a base64 string result in RXhhbXBsZUNsaWVudElkOkV4YW1wbGVTZWNyZXQ=.
For requested scope you can always use 'openid profile domain_api offline_access'. If you do not include offline_access you will not receive a refresh_token along with the access_token.

Example POST request for obtaining the access_token with client credentials in the request body:

curl -X POST 
-H "Content-Type: application/x-www-form-urlencoded" 
-d "client_id=ExampleClientId&client_secret=ExampleSecret&grant_type=password&username=developer@rushfiles.com&password=userPassword@&scope=openid profile domain_api offline_access" 
https://auth-test.rushfiles.com/connect/token

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijk5RDA1Njk0NjNCOEI4OUI3ODhFQzY0MjlDNUIzNUQ5NjlGQ0VENkEiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJtZEJXbEdPNHVKdDRqc1pDbkZzMTJXbjg3V28ifQ.eyJuYmYiOjE2MTc3MjE1MzksImV4cCI6MTYxNzgwNzkzOSwiaXNzIjoiaHR0cHM6Ly9hdXRoLXRlc3QucnVzaGZpbGVzLmNvbSIsImF1ZCI6WyJodHRwczovL2F1dGgtdGVzdC5ydXNoZmlsZXMuY29tL3Jlc291cmNlcyIsImRvbWFpbl9hcGkiLCJ3aXJ0ZWsucnVzaGZpbGVzLmNvbSJdLCJjbGllbnRfaWQiOiJQYXNzd29yZENyZWRlbnRpYWxzQ2xpZW50Iiwic3ViIjoiZGV2ZWxvcGVyQHJ1c2hmaWxlcy5jb20iLCJhdXRoX3RpbWUiOjE2MTc3MjE1MzksImlkcCI6ImxvY2FsIiwicHJpbWFyeV9kb21haW4iOiJ3aXJ0ZWsucnVzaGZpbGVzLmNvbSIsInNjb3BlIjpbIm9wZW5pZCIsInByb2ZpbGUiLCJkb21haW5fYXBpIiwib2ZmbGluZV9hY2Nlc3MiXSwiYW1yIjpbIlBhc3N3b3JkIl19.f6EYmdnolzg2nZPF6Kvh25UsEBT1bUJ90KGDQsZWWYt1zT-eWsIeHLICpZ7fbvnJ0VB2ErIhJi456SMwPPaunDVYysKGgjqr2SdozWB47cCbVdK-3reNCXefZm7DFjxm5dE2lxT9BGyDesymAyOwGZ3s62FYVrGw79RTxOefeP-1pdRLiRvzTrY8gizzF7vU5bxoPzBj71tPvD-WLmNG0PnD8qdSZNZ3D4NR7Lv7M0RGxJkWY5BreDFpXM_rtJF1fwMdmsvx9yZWQ5HrDBZgFbDSJI-CNzGXGkrrRZ7eRHzfZ5iUrcdI30YBVn9r5eZ5ZwhuynpxaidvcsioVYzGyQ",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "253806a88bcd25a05fe67615123a4e73827b2b5deb53e2c22ca7d6979017a36f"
}

Response information:

access_token is a JWT
expires_in is the access_token lifetime in seconds (starting from the UTC Date & Time of request).
refresh_token is an identifier which can be used to obtain a new access_token once the initial one is expired.
token_type contains the Authorization scheme to use when sending the token for authenticated API requests.

Storing tokens

You do not need to store user credentials for subsequent API requests. The access_token and refresh_token must be stored, ideally in an encrypted format.
It is especially important that the refresh_token is not leaked, since it can be used to obtain new access tokens (for refresh see 3).

2) Using the access token for authorized requests

Obtaining the user domain(s)

The domains where the user has access are stored within the access_token. The access_token needs to be decoded and parsed, and the following properties will stand out:

primary_domain - it is a string which contains the user's primary domain. This property is always set.
domains - it is a string or string array, containing any other domains, different from the primary_domain where the user has access. It is only set when the domains exist.

Example section of a JWT with multiple domains

 "primary_domain": "rushfiles.com",
  "domains": [
    "rushfiles.net",
    "test.rushfiles.com",
    "rushfiles.one",
    "beta.rushfiles.com",
    "rushfiles.cloud"
  ],

Example section of a JWT with a primary domain and a secondary domain:

  "primary_domain": "wirtek.rushfiles.com",
  "domains": "dev.rushfiles.com",

Making the request

Set the Authorization header on HTTP requests with the following format: Bearer access_token

Example request for user shares, with an access_token:

curl -X GET --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ijk5RDA1Njk0NjNCOEI4OUI3ODhFQzY0MjlDNUIzNUQ5NjlGQ0VENkEiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJtZEJXbEdPNHVKdDRqc1pDbkZzMTJXbjg3V28ifQ.eyJuYmYiOjE2MTc3MjE1MzksImV4cCI6MTYxNzgwNzkzOSwiaXNzIjoiaHR0cHM6Ly9hdXRoLXRlc3QucnVzaGZpbGVzLmNvbSIsImF1ZCI6WyJodHRwczovL2F1dGgtdGVzdC5ydXNoZmlsZXMuY29tL3Jlc291cmNlcyIsImRvbWFpbl9hcGkiLCJ3aXJ0ZWsucnVzaGZpbGVzLmNvbSJdLCJjbGllbnRfaWQiOiJQYXNzd29yZENyZWRlbnRpYWxzQ2xpZW50Iiwic3ViIjoiZGV2ZWxvcGVyQHJ1c2hmaWxlcy5jb20iLCJhdXRoX3RpbWUiOjE2MTc3MjE1MzksImlkcCI6ImxvY2FsIiwicHJpbWFyeV9kb21haW4iOiJ3aXJ0ZWsucnVzaGZpbGVzLmNvbSIsInNjb3BlIjpbIm9wZW5pZCIsInByb2ZpbGUiLCJkb21haW5fYXBpIiwib2ZmbGluZV9hY2Nlc3MiXSwiYW1yIjpbIlBhc3N3b3JkIl19.f6EYmdnolzg2nZPF6Kvh25UsEBT1bUJ90KGDQsZWWYt1zT-eWsIeHLICpZ7fbvnJ0VB2ErIhJi456SMwPPaunDVYysKGgjqr2SdozWB47cCbVdK-3reNCXefZm7DFjxm5dE2lxT9BGyDesymAyOwGZ3s62FYVrGw79RTxOefeP-1pdRLiRvzTrY8gizzF7vU5bxoPzBj71tPvD-WLmNG0PnD8qdSZNZ3D4NR7Lv7M0RGxJkWY5BreDFpXM_rtJF1fwMdmsvx9yZWQ5HrDBZgFbDSJI-CNzGXGkrrRZ7eRHzfZ5iUrcdI30YBVn9r5eZ5ZwhuynpxaidvcsioVYzGyQ" 
"https://clientgateway.rushfiles.com/api/users/{userId}/shares"

3) Refreshing the access token

The access_token has a lifetime of 24 hours and the refresh_token has a lifetime of 30 days. Once the access_token is expired, you will need to use the refresh_token to obtain a new access_token.

You can verify the expiration of the access_token in two ways:

using a client library which checks the lifetime of JWTs
handling an HTTP 401 Status Code response from the API

You need to make an HTTP POST request with the following:

URL of token endpoint - for development please use https://auth-test.rushfiles.com/connect/token
Authorization Header - Basic containing the client credentials consisting of a client_id and a client_secret. Required when client credentials not sent in body.
Content-Type Header - application/x-www-form-urlencoded
Request Body - must contain grant_type=refresh_token and the refresh_token itself. If not using Authorization header, must contain client_id and client_secret

Example request for obtaining a new access_token with client credentials in the request body:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" 
-d "client_id=ExampleClientId&client_secret=ExampleSecret&grant_type=refresh_token&refresh_token=0a81ce9e6d6e0bdd53043d8ca71ff6abeca64a5cab3bd34463727817886d14f9" 
https://auth-test.rushfiles.com/connect/token

Example response

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNiMmUwNmUwZWE2N2U2NjI5ZTY1YzdiNDNiYTQ0MGQ2IiwidHlwIjoiSldUIn0.eyJuYmYiOjE2MTc3ODgyNzgsImV4cCI6MTYxNzc4ODU3OCwiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMCIsImF1ZCI6IlBhc3N3b3JkQ3JlZGVudGlhbHNDbGllbnQiLCJpYXQiOjE2MTc3ODgyNzgsImF0X2hhc2giOiJtODVyeGlUWkQ2b29PZWIyZHNEMEJnIiwic3ViIjoib3ZpZGl1LnBvcEB3aXJ0ZWsuY29tIiwiYXV0aF90aW1lIjoxNjE3NzgyMjc5LCJpZHAiOiJsb2NhbCIsImFtciI6WyJQYXNzd29yZCJdfQ.T0Lb9FFqqNvJpeHPXLdNUzGzi9ENfJZ7zMJqbwpTWjEUqjPBrELMBSq5qQzNU_Fvh7Sll_lyC3Ov_pzoptggPND18zup900TqrRU2R7Zw2gDJ0yJub3Za3bXfluIFKpONbipvdxafpt5xHzlbMCOUsdb12hJHAt1ZyM6WtV4wr4DLQ50_Niznlyh_HCZrDjPo_hDT7-wTKPPOdOcUNMTA_mE3oWBhGR42KK63HeqVmSeCTXszR49dEdJR5zKnZ2BnikFjcvZVs74dnuHdOk9cm_d21SVTn8l6q_56zP_xXDL00S_JEMDgkUjlYm1TNbxbvxAbIU2tuFzmwuNKcy7aw",
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNiMmUwNmUwZWE2N2U2NjI5ZTY1YzdiNDNiYTQ0MGQ2IiwidHlwIjoiSldUIn0.eyJuYmYiOjE2MTc3ODgyNzgsImV4cCI6MTYxNzg3NDY3OCwiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMCIsImF1ZCI6WyJodHRwczovL2xvY2FsaG9zdDo1MDAwL3Jlc291cmNlcyIsImRvbWFpbl9hcGkiLCJvdmlkaXUuY29tIiwicnVzaGZpbGVzLmNvbSIsImZyb250c2hhcmUuZGsiXSwiY2xpZW50X2lkIjoiUGFzc3dvcmRDcmVkZW50aWFsc0NsaWVudCIsInN1YiI6Im92aWRpdS5wb3BAd2lydGVrLmNvbSIsImF1dGhfdGltZSI6MTYxNzc4MjI3OSwiaWRwIjoibG9jYWwiLCJwcmltYXJ5X2RvbWFpbiI6Im92aWRpdS5jb20iLCJkb21haW5zIjpbInJ1c2hmaWxlcy5jb20iLCJmcm9udHNoYXJlLmRrIl0sInNjb3BlIjpbIm9wZW5pZCIsInByb2ZpbGUiLCJkb21haW5fYXBpIiwib2ZmbGluZV9hY2Nlc3MiXSwiYW1yIjpbIlBhc3N3b3JkIl19.dNPT976T2YmNcyTypN-M5WEluuFSaarVd-Lbd7jahXjBzlyXZfMaeW3y_VuCVLYaqaezhLzx1AZ_B8OHkPz82WMIK6uZ7jK3Ndb7BYwgNnosj6yxLimx-s5pEJpRhO0_kWAdNP7OJnSIEaiVxNOOfEaW9bRaOr-FleMVoNs1dHz1rFCE9i2hHMV1D53tUdLQ2_7IzwGaTKCCsE6KO8vI3CvQ4T47nmg2O_sD8apJPWMnsTdtW8KVdnbNOt2vlxBL6pineIg-wHo68k1dD6HPv9OWHS5tvOgdYW_MDyrFN80Nv6jg4oHNAVyAiYYPgFNURxMUYr4EN_jv8TSzIL6ZSw",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "0a81ce9e6d6e0bdd53043d8ca71ff6abeca64a5cab3bd34463727817886d14f9"
}

Authorization with ApiKey

This type of authorization can be used for server to server, cron jobs, different types of integrations which require API access but do not need to impersonate a user.
Depending on the the endpoints you need to access:

Reseller ApiKey is used for endpoints related to reseller functionality
Company ApiKey is used for endpoints related to company / shares functionality

Obtaining the Reseller ApiKey

Open the reseller section of your domain (e.g. https://rushfiles.cloud/reseller).
Navigate on the My Account view, on the main reseller or a subreseller you want to use. Scroll down until you reach API Information.
The Api Key textbox will display the Reseller Api Key.

Using an ApiKey

Set the Authorization header on HTTP requests with the following format: ApiKey the_api_key

Example request for reseller companies (GET /api/resellers/{resellerId}/companies), with an ApiKey:

curl -X GET "https://clientgateway.rushfiles.cloud/api/resellers/2bda4a3c70bf4b069cb0f03f283c1ce1/companies" 
-H "accept: application/json" 
-H "Authorization: ApiKey NDJiMDcxOWYtNDUxNy00YTI0LTg4NzYtZDI3NjkzZTc5ZDIx"