API Reference

Introduction

Welcome to the ChannelSeal API documentation. This API allows you to integrate ChannelSeal's powerful features into your applications.

Base URL

Code
https://env.channelseal.com/capability

where env would be api for production and uat for UAT

capability would be platform or catalog

Authentication

ℹ️ Info All API requests require authentication using OAuth 2.0 Client Credentials flow.

OAuth 2.0 Client Credentials

ChannelSeal uses the OAuth 2.0 Client Credentials grant type for server-to-server authentication. This flow is ideal for applications that need to access API resources without user interaction.

Step 1: Obtain Client Credentials

1. Log in to your ChannelSeal Portal dashboard
2. Navigate to Settings → API Credentials
3. Click Create OAuth Client
4. Copy your client_id and client_secret

⚠️ Warning Never share your client credentials or commit them to version control. Use environment variables to store sensitive credentials.

Step 2: Request Access Token

Exchange your client credentials for an access token:

Code
curl --request POST \
  --url 'https://dev-channelseal.us.auth0.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{
  "client_id": "<your client id>",
  "client_secret": "<your client secret>",
  "audience": "https://api.channelseal.com",
  "grant_type": "client_credentials",
  "scope": "read write"
}'

Response:

Code
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 3: Use Access Token

Include the access token in all API requests:

Code
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

Access tokens expire after 1 hour (3600 seconds). When a token expires, request a new one using the same client credentials. Implement token refresh logic in your application to handle expiration automatically.

Example (JavaScript):

Code
class ChannelSealAuth {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    // Return cached token if still valid
    if (this.token && this.expiresAt > Date.now()) {
      return this.token;
    }

    // Request new token
    const response = await fetch('https://dev-channelseal.us.auth0.com/oauth/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: 'read write'
      })
    });

    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + (data.expires_in * 1000) - 60000; // Refresh 1 min early

    return this.token;
  }
}

// Usage
const auth = new ChannelSealAuth(
  process.env.CLIENT_ID,
  process.env.CLIENT_SECRET
);

const token = await auth.getToken();

Available Scopes

Scope	Description
read	Read access to resources
write	Create and update resources
delete	Delete resources
admin	Full administrative access

Request only the scopes your application needs. Multiple scopes can be space-separated: scope=read write delete

Rate Limiting

The API implements rate limiting to ensure fair usage:

• Free tier: 100 requests per hour
• Pro tier: 1,000 requests per hour
• Enterprise tier: Custom limits

Rate limit information is included in response headers:

Code
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1634567890

Error Handling

The API returns errors using the RFC 9457 Problem Details specification. All error responses use the application/problem+json content type.

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing access token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource state conflict
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Problem Details Response Format

All errors follow the RFC 7807 standard with these fields:

Field	Type	Description
type	string	URI reference identifying the problem type
title	string	Short, human-readable summary
status	integer	HTTP status code
detail	string	Human-readable explanation specific to this occurrence
instance	string	URI reference identifying the specific occurrence
errors	array	(Optional) Validation errors for 422 responses

Error Examples

400 Bad Request

Code
{
  "type": "https://api.channelseal.com/problems/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request could not be understood due to malformed syntax",
  "instance": "/api/v1/resources?limit=invalid"
}

401 Unauthorized

Code
{
  "type": "https://api.channelseal.com/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The access token is invalid or has expired",
  "instance": "/api/v1/resources"
}

403 Forbidden

Code
{
  "type": "https://api.channelseal.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to access this resource. Required scope: 'admin'",
  "instance": "/api/v1/resources/res_123abc"
}

404 Not Found

Code
{
  "type": "https://api.channelseal.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource 'res_123abc' does not exist",
  "instance": "/api/v1/resources/res_123abc"
}

409 Conflict

Code
{
  "type": "https://api.channelseal.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A resource with this name already exists",
  "instance": "/api/v1/resources",
  "conflicting_resource": "res_789xyz"
}

422 Unprocessable Entity (Validation Errors)

Code
{
  "type": "https://api.channelseal.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation",
  "instance": "/api/v1/resources",
  "errors": [
    {
      "field": "name",
      "message": "Name is required and cannot be empty",
      "code": "required"
    },
    {
      "field": "email",
      "message": "Email must be a valid email address",
      "code": "invalid_format",
      "rejected_value": "not-an-email"
    },
    {
      "field": "status",
      "message": "Status must be one of: active, inactive, pending",
      "code": "invalid_enum",
      "rejected_value": "archived",
      "allowed_values": ["active", "inactive", "pending"]
    }
  ]
}

429 Rate Limit Exceeded

Code
{
  "type": "https://api.channelseal.com/problems/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 1000 requests per hour",
  "instance": "/api/v1/resources",
  "retry_after": 1800
}

Response Headers:

Code
Retry-After: 1800
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707649200

500 Internal Server Error

Code
{
  "type": "https://api.channelseal.com/problems/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request",
  "instance": "/api/v1/resources",
  "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

ℹ️ Info Include the trace_id when contacting support to help us investigate the issue.

Error Handling Best Practices

1. Always check the status code before processing the response
2. Parse the Problem Details to understand what went wrong
3. Handle 401 errors by refreshing your access token
4. Respect 429 responses and implement exponential backoff
5. Log trace_id values from 500 errors for support requests
6. Display validation errors from 422 responses to users

Example Error Handling (JavaScript):

Code
async function makeApiRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const problem = await response.json();

    switch (problem.status) {
      case 401:
        // Refresh token and retry
        await refreshAccessToken();
        return makeApiRequest(url, options);

      case 422:
        // Handle validation errors
        throw new ValidationError(problem.errors);

      case 429:
        // Wait and retry
        const retryAfter = problem.retry_after || 60;
        await sleep(retryAfter * 1000);
        return makeApiRequest(url, options);

      case 500:
        // Log trace_id and notify support
        console.error(`Server error: ${problem.trace_id}`);
        throw new ServerError(problem);

      default:
        throw new ApiError(problem);
    }
  }

  return response.json();
}

Common Parameters

Pagination

List endpoints support pagination using the following parameters:

Parameter	Type	Default	Description
number	integer	1	Page number
size	integer	20	Elements/ items per page or page size (max: 100)
sortBy	string	updatedAt	Sort by property name of resource
sortOrder	string	DESC	Sort order, ASC (ascending) or DESC (descending)
totalElements	integer	1	Total number of elements/ items
totalPages	integer	1	Total number of pages

Response includes:

Code
{
  "content": [
    {}
  ],
  "page": {
    "size": 0,
    "number": 0,
    "totalElements": 0,
    "totalPages": 0
  }
}

Filtering

Many endpoints support filtering using query parameters:

Code
GET /api/v1/resources?status=active

Sorting

Use the sort parameter to order results:

Code
GET /api/v1/resources?sortBy=createdAt&sortOrder=ASC

---

---

Changelog

Version 0.1.0 (2026-02-11)

• Initial API release
• Added Resources endpoints

---

Support

Need Help?

• Documentation: docs.channelseal.com
• Email: support@channelseal.com

Report Issues

Found a bug or have a feature request? Open an issue on our GitHub repository.

---

Terms and Compliance

By using the ChannelSeal API, you agree to our:

• Privacy Policy

Data Security

All API requests must use HTTPS. Requests made over HTTP will fail.

GDPR Compliance

ChannelSeal is GDPR compliant. For data deletion requests, contact privacy@channelseal.com.

---

ℹ️ Info Questions? This API documentation is constantly evolving. For the latest updates and detailed guides, visit our developer portal.