🚀Quick Start

To use the API of Rekaz Platform, you must first obtain an access token. To do that, you need a username, password and the tenant name.

API Key Management

Generating an API Key

1. Log into the dashboard.

2. Navigate to User Management > API Keys.

3. Click on Generate New Key. The key and its secret will be displayed once in a modal—make sure to copy and store the secret immediately.

Regenerating an API Key

To regenerate an API key:

1. Go to User Management > API Keys.

2. Select Regenerate Key for the key you wish to replace.

3. Confirm the action. Note that regenerating a key will revoke the old one and display the new secret once.

Using API Keys for Authentication

To authenticate API requests using Basic Authentication:

1. Combine the API key and secret into a single string with the format: key:secret.

2. Encode this string in Base64 format.

3. Include the Base64-encoded string in your HTTP request headers as follows:

Authorization: Basic {base64_string}

Replace {base64_string} with your Base64-encoded credentials. Always ensure you are making requests over HTTPS to secure your credentials.

🌐 Examples for Clarity

To make it perfectly clear, we'll go through 2 examples, one for creating a customer, and the other for creating a subscription. These are typically the first 2 use cases of our api after obtaining an access token.

Example 1: Post a customer

POST/api/app/customer

Body

application/jsontext/jsonapplication/*+json

namenullable string

mobileNumbernullable string

addressnullable string

customerTypeSnam.Platform.Customers.CustomerType (enum)

12

crNumbernullable string

vatNumbernullable string

branchIdnullable string (uuid)

Response

200400401403404500501

Success

Body

text/plainapplication/jsontext/json

string (uuid)

Request

JavaScriptCurlPython

const response = await fetch('/api/app/customer', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400401403404500501

123e4567-e89b-12d3-a456-426614174000

Assume your access token is the string "abcdefgh". Note that tokens are a lot longer in reality. Let's send a POST request to /api/app/customer Depending on your programming language, framework or tool, you need to add HTTP headers as follows:

Content-Type: "application/json"
Authorization: "Basic abcdefgh"

For this particular request, the body needs to define the customer information, these values:

{
    "name": "Abdulaziz",
    "mobileNumber": "05123456789",
    "customerType": 1 // 1 for individuals, 2 for corporates
}

Sending this request should return a 200 OK response. If it returns a 401 Unauthroized, check these options:

• Make sure you formatted the access token in the headers correctly as shown above.

• The access token might have expired, since it only lasts an hour.

  • If it has expired, request a new access token.

Example 2: Post a subscription

Let's send a POST request to /api/app/subscription

POST/api/app/subscription

Body

application/jsontext/jsonapplication/*+json

customerIdstring (uuid)

startAtstring (date-time)

discountnumber (double)

branchIdstring (uuid)

itemsnullable array of Snam.Platform.Subscriptions.Dtos.CreateUpdateSubscriptionItemDto (object)

Response

200400401403404500501

Success

Request

JavaScriptCurlPython

const response = await fetch('/api/app/subscription', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

400401403404500501

{
  "error": {
    "code": "text",
    "message": "text",
    "details": "text",
    "validationErrors": [
      {
        "message": "text",
        "members": [
          "text"
        ]
      }
    ]
  }
}

For this particular request, the body needs to define the subscription information, these values:

{
  "customerId": "guid",
  "startAt": "timestamp in the ISO 8601 format",
  "discount": 0,
  "branchId": "guid",
  "items": [
    {
      "priceId": "guid",
      "quantity": 0
    }
  ]
}

Getting the CustomerId or PriceId can be either from the API's or copy it directly from the dashboard Customers > Customer List > Copy Id

Sending this request should return a 200 OK response. If it returns a 401 Unauthroized, check these options:

• Make sure you formatted the access token in the headers correctly as shown above.

• The access token might have expired, since it only lasts an hour.

  • If it has expired, request a new access token.

If it returns a 400 Bad Request, you should check the formatting of the values in the request's body.

That is all for now. Please report any bugs or weird behavior in our api to us.