Access API user guide

1. Introduction

Welcome to the RADKit Access Public API! This API allows developers to interact with RADKit Access, to generate one-time passwords (OTPs) and retrieve a RADKit service status.

This guide covers authentication, available public API endpoints, and token management procedures.

2. Authentication

RADKit Access uses OAuth 2.0 with the Client Credentials Grant for secure access.

Use the RADKit Admin Client to generate your client_id and client_secret.

example:

client = sso_login("someone@example.com")
credentials = client.admin_client().generate_client_credentials()
print(credentials.client_id)
print(credentials.client_secret)
print(credentials.expires_at)

Alternatively, you can generate and use API tokens for authentication:

client = sso_login("someone@example.com")
api_token = client.admin_client().generate_api_token(lifetime=30)  # 30 days
print(api_token.token.token)  # The JWT token string
print(api_token.expires_at)

Important

Do not hard-code your credentials or API tokens in your application. Use environment variables or secure vaults to manage sensitive information.

Important

To be able to generate client credentials or API tokens you must hold the necessary claims, which need to be assigned first by the RADKit Access administrators.

Important

API tokens have configurable lifetimes (default 7 days, maximum depends on system configuration). Monitor token expiration and regenerate as needed. You can list and revoke API tokens using the admin client.

Important

Tagged Client IDs: When generating API tokens, you can specify a different endpoint_id to associate the token with a specific identity. This is particularly useful for automation scenarios where a generic automation account needs to perform actions on behalf of different customers or organizational units. Use email aliasing with “+” syntax (e.g., user+customer-a@cisco.com) to create tagged identities. See examples below for usage patterns.

Important

Always retrieve OAuth2 endpoints dynamically via the .well-known/openid-configuration URL.

Example:

curl https://devel.radkit-cloud.cisco.com/.well-known/openid-configuration
{
  "issuer":"https://devel.radkit-cloud.cisco.com",
  "jwks_uri":"https://devel.radkit-cloud.cisco.com/oauth2/keys",
  "token_endpoint":"https://devel.radkit-cloud.cisco.com/oauth2/token",
  "revocation_endpoint":"https://devel.radkit-cloud.cisco.com/oauth2/revoke",
  "userinfo_endpoint":"https://devel.radkit-cloud.cisco.com/oauth2/user_info"
}

Authentication flow:

  1. Obtain an access token using either client credentials or an API token (Section 5.1 describes this process).

  2. Use the access token as a Bearer token in the Authorization header for all API calls.

3. Base URL

All endpoints are relative to:

{{baseURL}}

Replace {{baseURL}} with your actual RADKit Access Cloud environment URL.

4. Public API Endpoints

4.1 Generate Service OTP

Purpose: Request a new Service One-Time Password (OTP) for an endpoint.

  • Method: POST

  • URL: /public/otp/certificate

Request Body (JSON):

{
  "owner": "user@example.com",
  "endpoint_id": "endpoint-identifier",
  "description": "description of the OTP purpose"
}

Example Request:

curl --request POST '{{baseURL}}/public/otp/certificate' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "owner": "user@example.com",
    "endpoint_id": "endpoint-identifier",
    "description": "description of the endpoint"
  }'

Example Success Response (HTTP 200 OK):

{
  "otp": "abcd-1234-efgh-5678",
}

Example Error Response (HTTP 400 Bad Request):

{
  "success": false,
  "details": "Missing required field 'owner'",
  "retry": false
}

4.2 Get Service Status

Purpose: Retrieve the status of a registered service.

  • Method: GET

  • URL: /public/admin/service/status/:service_id

Path Parameter:

  • service_id — ID of the service to query.

Example Request:

curl --request GET '{{baseURL}}/public/admin/service/status/123-123-123' \
  --header 'Authorization: Bearer {access_token}'

Example Success Response (HTTP 200 OK):

{
  "service_id": "123-123-123",
  "active": true,
  "online": true,
}

Example Error Response (HTTP 404 Not Found):

{
 "success": false,
 "details": "Unknown Service ID",
 "retry": false
}

5. OAuth2 Token Management

5.1 Retrieve New Access Token

You can obtain an access token using either OAuth 2.0 client credentials or API tokens.

  • Method: POST

  • URL: /auth/token

Using OAuth client credentials:

Example Request:

curl --request POST '{{baseURL}}/oauth2/token?grant_type=client_credentials' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}'

Using API tokens:

Example Request:

curl --request POST '{{baseURL}}/auth/token' \
  --header 'Authorization: JWT {api_token}'

Both methods return the same response format:

Example Success Response (HTTP 200 OK):

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_remaining_lifetime": 600,
  "radkit_access_token": "eyJhbGciOi...",
  "identity": "user@example.com",
  "admin_level": 0
}

Example Error Response (HTTP 401 Unauthorized):

{
 "success": false,
 "details": "Invalid credentials",
 "retry": false
}

5.2 Revoke Access Token

  • Method: POST

  • URL: /oauth2/revoke

Query Parameter:

  • token — the access token to revoke.

Example Request:

curl --request POST '{{baseURL}}/oauth2/revoke?token={your_access_token}' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}'

Example Success Response (HTTP 204 No Content):

Example Error Response (HTTP 400 Bad Request):

{
 "success": false,
 "details": "Token unknown or expired",
 "retry": false
}

6. Tagged Client IDs for Automation

Generate API tokens with specific endpoint_id values using email aliasing (user+tag@domain.com) for automation scenarios where different customers/units need separate identities:

client = sso_login("automation@cisco.com")
customer_token = client.admin_client().generate_api_token(
    lifetime=30, endpoint_id="automation+customer-a@cisco.com")

Usage in service enrollment - see Service enrollment for complete examples.

Benefits: Clear ownership, audit trails, access control, and organizational separation.

7. Common Errors

Error Code

Description

Action

401

Unauthorized / Invalid token

Refresh token or reauthenticate

400

Bad request parameters

Check API parameters and request body

403

Forbidden

Verify client permissions

404

Not Found

Check if the service or resource exists

500

Server error

Contact RADKit Access Cloud support

7. Appendix

  • Grant Type Used: client_credentials

  • Token Placement: Authorization Header (Bearer token)

  • OAuth2 Discovery: .well-known/openid-configuration strongly recommended.

  • Content-Type: Always use application/json for request bodies unless otherwise stated.

  • Download Postman Collection: Download here

You’re Ready!

Use the APIs securely, automate your services, and ensure that token management is dynamic and standards-compliant.