Api Keys

Managing Authentication and Access Control

The API keys endpoint in the Babel Licensing Service API is a crucial component designed for the management and handling of API keys, which are essential for authenticating and gaining access to the service. This endpoint supports multiple HTTP methods, each serving a specific purpose in the lifecycle of API keys.

Get

This method is utilized to fetch information about existing API keys. It allows users to access details such as key identifiers, associated permissions, and the user to which each key is assigned. This function is essential for monitoring and managing API key distribution, ensuring each key is used in accordance with its intended purpose and security protocols.

Retrieves the API keys.

GET/v1/api-keys

Query parameters

Response

200default

Success

Body

application/json

successboolean

success is a field indicating whether the request was successful.

codeinteger (int32)

code is a field representing the status code of the response.

messagestring

message is a field containing a message about the response, typically used in case of an error.

apiKeysarray of ApiKey (object)

api_keys is a repeated field containing the API keys returned by the request.

totalApiKeysCountinteger (int32)

total_api_keys_count is a field indicating the total number of API keys available.

Request

JavaScriptCurl

const response = await fetch('/v1/api-keys', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "success": false,
  "message": "text",
  "apiKeys": [
    {
      "name": "text",
      "key": "text",
      "clientSecret": "text",
      "createdDate": "text",
      "expireDate": "text",
      "ownerId": "text",
      "revoked": false,
      "description": "text"
    }
  ]
}

Examples

C#

using System.Net.Http;
using Babel.Licensing.Service.Management;

// See WebApiClient in Code Examples paragraph
using var httpClient = CreateHttpClient();

var request = new GetApiKeysRequest();
var httpMessage = MakeApiRequest(request, HttpMethod.Get, "/v1/api-keys");

var result = await httpClient.SendAsync(httpMessage);
var response = await ParseResponseAsync<GetApiKeysResponse>(result);

VB.NET

Imports System.Net.Http
Imports Babel.Licensing.Service.Management

' See WebApiClient in Code Examples paragraph
Using httpClient As HttpClient = CreateHttpClient()

   Dim request As New GetApiKeysRequest()
   Dim httpMessage As HttpRequestMessage = MakeApiRequest(request, HttpMethod.Get, "/v1/api-keys")
   
   Dim result As HttpResponseMessage = Await httpClient.SendAsync(httpMessage)
   Dim response As GetApiKeysResponse = Await ParseResponseAsync(Of GetApiKeysResponse)(result)

End Using

Shell

curl -X 'GET' \
  'https://localhost:5455/v1/api-keys' \
  -H 'accept: application/json' \
  -H 'x-api-key: ApiKey'

Post

The POST method facilitates the generation of new API keys. It is used for creating keys that grant access to the API, specifying the scope and level of access each key provides. This method is crucial for expanding access to new users or services, enabling controlled and tracked interactions with the API.

Creates an API key using the information provided in the request body.

POST/v1/api-keys

Body

application/json

apiKeyApiKey (object)

ApiKey is a message type representing an API key.

Response

200default

Success

Body

application/json

apiKeyIdinteger (int32)

api_key_id is the ID of the created API key.

successboolean

success indicates whether the operation was successful.

codeinteger (int32)

code is the status code of the operation.

messagestring

message is a human-readable message indicating the result of the operation.

apiKeystring

api_key is the created API key.

Request

JavaScriptCurl

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

Response

{
  "success": false,
  "message": "text",
  "apiKey": "text"
}

Examples

C#

using System.Net.Http;
using Babel.Licensing.Service.Management;

using var httpClient = CreateHttpClient();

var create = new InsertApiKeyRequest();
create.ApiKey = new ApiKey();
// Assign a name to the API key
create.ApiKey.Name = "Administrator API Key";
// Set the Administrator User ID
create.ApiKey.OwnerId = "725dc5f3-a4d2-4566-be63-356daa8a7367";
// Set permissions (Read = 1, Write = 2, Delete = 4)
create.ApiKey.Permissions = 7;

var httpMessage = MakeApiRequest(create, HttpMethod.Post, "/v1/api-keys");
var result = await httpClient.SendAsync(httpMessage);
var createResponse = await ParseResponseAsync<InsertApiKeyResponse>(result);

VB.NET

Imports System.Net.Http
Imports Babel.Licensing.Service.Management

Using httpClient As HttpClient = CreateHttpClient()

    ' Create a new instance of the InsertApiKeyRequest
    Dim create As New InsertApiKeyRequest()
    create.ApiKey = New ApiKey()

    ' Assign a name to the API key
    create.ApiKey.Name = "Administrator API Key"
    ' Set the Administrator User ID
    create.ApiKey.OwnerId = "725dc5f3-a4d2-4566-be63-356daa8a7367"
    ' Set permissions (Read = 1, Write = 2, Delete = 4)
    create.ApiKey.Permissions = 7
    
    ' Create an HTTP request message for the API call
    Dim httpMessage As HttpRequestMessage = MakeApiRequest(create, HttpMethod.Post, "/v1/api-keys")
    ' Send the request asynchronously and wait for the result
    Dim result As HttpResponseMessage = Await httpClient.SendAsync(httpMessage)
    ' Parse the response asynchronously and get the response object
    Dim createResponse As InsertApiKeyResponse = Await ParseResponseAsync(Of InsertApiKeyResponse)(result)

End Using

Shell

curl -X 'POST' \
  'https://localhost:5455/v1/api-keys' \
  -H 'accept: application/json' \
  -H 'x-api-key: ApiKey' \
  -H 'Content-Type: application/json' \
  -d '{
  "apiKey": {
    "name": "Administrator API Key",
    "ownerId": "725dc5f3-a4d2-4566-be63-356daa8a7367",
    "permissions": 7,
    "description": "The administrator API key with read, write and delete rights."
  }
}'

Put

Employing the PUT method allows for updates to the attributes of existing API keys. This might include changing the scope of access, modifying associated permissions, or updating the key’s expiration date. This method is vital for maintaining the relevance and security of API keys, adapting them to changing requirements or security policies.

Updates the API key specified in the request body.

PUT/v1/api-keys

Body

application/json

apiKeyApiKey (object)

ApiKey is a message type representing an API key.

Response

200default

Success

Body

application/json

successboolean

success indicates whether the operation was successful.

codeinteger (int32)

code is the status code of the operation.

messagestring

message is a human-readable message indicating the result of the operation.

Request

JavaScriptCurl

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

Response

{
  "success": false,
  "message": "text"
}

Examples

C#

using System.Net.Http;
using Babel.Licensing.Service.Management;

using var httpClient = CreateHttpClient();

var update = new UpdateApiKeyRequest();
update.ApiKey = new ApiKey();
// Set the ID of the API key to update
update.ApiKey.Id = 3;
// Set permissions (Read = 1, Write = 2, Delete = 4)
update.ApiKey.Permissions = 7;
// Change description
update.ApiKey.Description = "Assign read write permissions to sales.";

var httpMessage = MakeApiRequest(update, HttpMethod.Put, "/v1/api-keys");

var result = await httpClient.SendAsync(httpMessage);
var updateResponse = await ParseResponseAsync<UpdateApiKeyResponse>(result);

VB.NET

Imports System.Net.Http
Imports Babel.Licensing.Service.Management

Using httpClient As HttpClient = CreateHttpClient()

    ' Create a new instance of the UpdateApiKeyRequest
    Dim update As New UpdateApiKeyRequest()
    update.ApiKey = New ApiKey()
    ' Set the ID of the API key to update
    update.ApiKey.Id = 3
    ' Set permissions (Read = 1, Write = 2, Delete = 4)
    update.ApiKey.Permissions = 7
    ' Change the description of the API key
    update.ApiKey.Description = "Assign read write permissions to sales."

    Dim httpMessage As HttpRequestMessage = MakeApiRequest(update, HttpMethod.Put, "/v1/api-keys")

    Dim result As HttpResponseMessage = Await httpClient.SendAsync(httpMessage)
    Dim updateResponse As UpdateApiKeyResponse = Await ParseResponseAsync(Of UpdateApiKeyResponse)(result)

End Using

Shell

curl -X 'PUT' \
  'https://localhost:5455/v1/api-keys' \
  -H 'accept: application/json' \
  -H 'x-api-key: ApiKey' \
  -H 'Content-Type: application/json' \
  -d '{
  "apiKey": {
    "id": 3,
    "name": "Sales API keys",
    "permissions": 3,
    "description": "Assign read write permissions to sales."
  }
}'

Delete

The DELETE method is used for invalidating and removing API keys from the system. This action is typically taken when a key is no longer needed, has been compromised, or when its associated user or service no longer requires access to the API. This is a critical step in API key lifecycle management, ensuring that only active and secure keys are in circulation.

Deletes an API key specified by the ID.

DELETE/v1/api-keys/{apiKeyId}

Path parameters

apiKeyId*integer (int32)

api_key_id is the ID of the API key to be deleted.

Response

200default

Success

Body

application/json

successboolean

success indicates whether the operation was successful.

codeinteger (int32)

code is the status code of the operation.

messagestring

message is a human-readable message indicating the result of the operation.

Request

JavaScriptCurl

const response = await fetch('/v1/api-keys/{apiKeyId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "success": false,
  "message": "text"
}

Examples

C#

using System.Net.Http;
using Babel.Licensing.Service.Management;

using var httpClient = CreateHttpClient();

var delete = new DeleteApiKeyRequest();
// Set the ID of the API key to delete
delete.ApiKeyId = 27;

var httpMessage = MakeApiRequest(delete, HttpMethod.Delete, $"/v1/api-keys/{delete.ApiKeyId}");
var result = await httpClient.SendAsync(httpMessage);

var deleteResponse = await ParseResponseAsync<DeleteApiKeyResponse>(result);

VB.NET

Imports System.Net.Http
Imports Babel.Licensing.Service.Management

' Create the HttpClient using the CreateHttpClient method
Using httpClient As HttpClient = CreateHttpClient()

    ' Create a new instance of the DeleteApiKeyRequest
    Dim delete As New DeleteApiKeyRequest()

    ' Set the ID of the API key to delete
    delete.ApiKeyId = 27

    ' Create an HTTP request message for the API call
    Dim httpMessage As HttpRequestMessage = MakeApiRequest(delete, HttpMethod.Delete, $"/v1/api-keys/{delete.ApiKeyId}")

    ' Send the request asynchronously and wait for the result
    Dim result As HttpResponseMessage = Await httpClient.SendAsync(httpMessage)

    ' Parse the response asynchronously and get the response object
    Dim deleteResponse As DeleteApiKeyResponse = Await ParseResponseAsync(Of DeleteApiKeyResponse)(result)

End Using

Shell

curl -X 'DELETE' \
  'https://localhost:5455/v1/api-keys/27' \
  -H 'accept: application/json' \
  -H 'x-api-key: ApiKey'

Each interaction with this endpoint ensures secure and controlled access to the Babel Licensing Service, making it a fundamental aspect of the API's security and access management features. The endpoint's responses are well-defined, indicating successful operations or errors, thereby facilitating efficient error handling and debugging.