1. In the RedApp, click on the RedAPI icon at the top right.

Note: If you would like to make use of the RedAPI but you do not see the RedAPI icon in the RedApp, please contact your account manager to arrange access.

2. On the RedAPI page, click on Service accounts in the sidebar.

3. Click on Add a service account at the top right.

4. Under Service account details, add a name and description for the account.

5. Under Partner and company access, select a partner from the menu or search for a specific partner. When you're ready, click Assign.

A list of customers under this partner will automatically be shown in the Select specific customer field. There, you can include/exclude customers by ticking/unticking company names from the list. The default is for all customers to be selected. When you're ready, click Assign.

If you want new customers to have RedAPI access by default, you can enable Auto-assign all future customers.

6. Under Keys, click Create key.

7. Provide a descriptive name for the key. Then click Next.

You will now need to authenticate with your RedApp credentials. A private and a public key will be generated. Click Download to save the keys to a location of your choice. Then click Done.

9. The newly created account, with its client ID, will now appear in the list on the Service accounts page.

You can filter this list by clicking on the filter icon at the top right of the table, next to the search field. You can filter by account status, key status or account creation date.

10. If you need to delete an account, locate the account in the list on the Service accounts page. Click on the menu (ellipsis) to its right and click Delete account. You will need to confirm the deletion and authenticate with your admin credentials.

 {
"jti": "7186f958-1b78-479e-8f1f-72a44874c9ac",
"sub": "5d41008d-7388-4eec-b90f-f8234f461db6",
"iat": 1677232754,
"nbf": 1677232754,
"exp": 1677233054,
"iss": "5d41008d-7388-4eec-b90f-f8234f461db6",
"aud": "https://id.redstor.com/connect/token"
} 

3. Sign the JWT using the private key.

4. Get an access token from the token_endpoint.

POST https://id.redstor.com/connect/token HTTP/1.1
Host: id.redstor.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=api.read%20api.write&resource=https%3A%2F%2Fapi.
redstor.com%2F&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=<SIGNED-JWT>

5. The token_endpoint will respond with an access token on success:

{
"access_token": "<TOKEN-VALUE>",
"expires_in": 3600,
"scope": "api.read api.write",
"token_type": "Bearer"
}

6. Invoke the API endpoint with the returned access token:

GET https://api.redstor.com/<ENDPOINT> HTTP/1.1
Host: api.redstor.com
Authentication: Bearer <TOKEN-VALUE>
... 

7. If the token expires, repeat this process to get a new access token.

Sample code

The following packages are used in this code:

• IdentityModel/6.0.0

• Microsoft.IdentityModel.Tokens/6.10.0

• System.IdentityModel.Tokens.Jwt/6.10.0

var clientId = "<CLIENT-ID>";
var discovery = await httpClient.GetDiscoveryDocumentAsync("https://id.redstor.com/");
if (discovery.IsError) { /* ... */ }

// get private key

var privateJwk = new JsonWebKey(File.ReadAllText("private.jwk"));
var signingCredentials = new SigningCredentials(privateJwk, "RS256");

// create and sign client_assertion

var now = DateTime.UtcNow;
var token = new JwtSecurityToken(
    clientId,
    discovery.TokenEndpoint,
    new List<Claim>
    {
      new(JwtClaimTypes.JwtId, CryptoRandom.CreateUniqueId()),
      new(JwtClaimTypes.Subject, clientId),
      new(JwtClaimTypes.IssuedAt, now.ToEpochTime().ToString(), ClaimValueTypes.Integer64)
    },
    now,
    now.AddMinutes(5),
    signingCredentials);
var tokenHandler = new JwtSecurityTokenHandler();
var clientAssertion = tokenHandler.WriteToken(token);

// authenticate

var tokenResponse = await httpClient.RequestClientCredentialsTokenAsync(
    new ClientCredentialsTokenRequest
    {
      Address = discovery.TokenEndpoint,
      ClientAssertion =
      {
        Type = OidcConstants.ClientAssertionTypes.JwtBearer,
        Value = clientAssertion
      },
      Scope = "api.read api.write",
    });

if (tokenResponse.IsError) { /* ... */ }

// invoke RedAPI

httpClient.SetBearerToken(tokenResponse.AccessToken);

var response = await httpClient.GetAsync("https://api.redstor.com/...")

Errors

Redstor uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, any codes in the 2xx range indicate success, while codes in the 4xx range indicate an error that failed given the information provided. Any codes in the 5xx range indicate an error in Redstor’s services. Most errors have a descriptive error message included.

Pagination

GET /endpoint?maxResult=2&shouldReturnCount=true 

1{ 
2   "nextPageToken":"CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA", 
3   "totalCount":10, 
4   "results":[] 
16} 

GET /endpoint?maxResult=2&shouldReturnCount=true&pageToken=CiAKGjBpNDd2N 

1{
2   "nextPageToken":" YjBpOXA274453707NDd2Nmp2Zml2cXR", 
3   "totalCount":-1, 
4   "results":[] 
16}