General

Authentication

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

// Generate RSA 2048-bit keypair

var key = RSA.Create(2048);
var keyId = CryptoRandom.CreateUniqueId();
var publicKey = new RsaSecurityKey(key.ExportParameters(false))
{
    KeyId = keyId
};
var publicAndPrivateKey = new RsaSecurityKey(key.ExportParameters(true))
{
    KeyId = keyId
};
var publicJwk = JsonWebKeyConverter.ConvertFromRSASecurityKey(publicKey);
var publicAndPrivateJwk = JsonWebKeyConverter.ConvertFromRSASecurityKey(publicAndPrivateKey);
File.WriteAllText("public.jwk", JsonExtensions.SerializeToJson(publicJwk));
File.WriteAllText("private.jwk", JsonExtensions.SerializeToJson(publicAndPrivateJwk));

// public.jwk is sent to Redstor when requesting a new API client
// private.jwk is stored securely and used for authentication

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.

Please see each section for more details on possible error responses.

Pagination

Pagination is implemented uniformly across all the APIs. Redstor’s pagination strategy follows the continuation token style. 

Pagination Parameters 

Three parameters define the pagination request: 

maxResults (optional) 

Query Parameter — The maximum number of results to return format: int32 
Notes — Use a value between 1 and 100. Defaults to 30 

pageToken (optional) 

Query Parameter — Token to get the next page: String 

shouldReturnCount (optional) 

Query Parameter — Indicate whether or not the response should include the total number of items that match the set of constraints: boolean
Notes — The count will not be returned by default. When the count is present, it would be available on the first page of the paged dataset 

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

The API will continue to return a reference to the next page of results in the nextPageToken property with each response until all pages of the results have been read. Therefore, to read all results, continue to query the endpoint, each time passing in the pageToken until the nextPageToken property isn’t returned.

Versioning 

Versioning an API can help to ensure compatibility with existing clients, improve stability, provide better control over the deprecation process, and improve documentation. While path versioning was originally used as the versioning strategy for the API Portal, this has now been standardised to query parameter version. This approach involves including the API version as a query parameter when making requests. For example, an API endpoint might have a URL structure like "http://api.example.com/endpoint?apiVersion=1", with the desired version specified as a query parameter. When a breaking change is introduced on the endpoint, a new version of that endpoint is created, and the query parameter will then updated as follows: "http://api.example.com/endpoint?apiVersion=2".

Note: Major and minor versions can be used. When no version is specified, the latest version is to be assumed.

OpenAPI Specification

Public OpenAPI specification.

Note: The specification for RedAPI V1 (soon to be deprecated) can be found here.