End Customer Portal

Manage end customers and their API keys. These endpoints allow you to:

• List and view your end customers

• Create new end customers with API keys

• Update customer details

• Monitor usage and rate limits per customer

• Rotate or revoke customer API keys

Authentication: End Customer Portal endpoints require only your platform API key. The X-Customer-Key header is not used for these endpoints.

List end customers

get

Retrieves a paginated list of all end customers for the authenticated partner.

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Query parameters

limitinteger · min: 1 · max: 100Optional

Maximum number of customers to return (1-100)

Default: 25

offsetintegerOptional

Number of customers to skip for pagination

Default: 0

Responses

200

List of customers

application/json

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

get

/customers

HTTPcURLJavaScriptPython

GET /v1/customers HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "customer_list",
  "data": {
    "customers": [
      {
        "id": "cust_abc123xyz",
        "name": "Acme University",
        "createdAt": "2025-01-15T10:30:00Z"
      },
      {
        "id": "cust_def456uvw",
        "name": "State College",
        "createdAt": "2025-01-20T14:45:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_portal001",
    "timestamp": "2025-01-30T12:00:00Z"
  },
  "pagination": {
    "total": 2,
    "limit": 25,
    "offset": 0,
    "hasMore": false
  }
}

Create end customer

post

Creates a new end customer and generates their API key.

The API key is only returned in this response and when calling GET /customers/{customerId}. Store it securely as it cannot be retrieved later (only rotated).

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Body

application/json

namestring · min: 1 · max: 255Required

Customer name (must be unique within your account)

Example: Acme University

Responses

201

Customer created successfully

application/json

400

Invalid request parameters

application/json

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

409

Conflict - customer name already exists

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/customers

HTTPcURLJavaScriptPython

POST /v1/customers HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "name": "Acme University"
}

{
  "object": "customer",
  "data": {
    "id": "cust_abc123xyz",
    "name": "Acme University",
    "apiKey": "ck_live_abc123xyz789",
    "createdAt": "2025-01-30T12:00:00Z"
  },
  "meta": {
    "requestId": "req_portal002",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}

Get end customer

get

Retrieves a specific end customer including their API key.

Use this endpoint to retrieve a customer's API key if needed (e.g., to share with the customer).

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Path parameters

customerIdstringRequired

Unique customer identifier. Use sandbox examples below for testing.

Example: {"value":"clx8f2k9h0001qr5tgvwxyz12","summary":"Northern Virginia Community College"}

Responses

200

Customer details

application/json

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

404

Resource not found

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

get

/customers/{customerId}

HTTPcURLJavaScriptPython

GET /v1/customers/{customerId} HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "customer",
  "data": {
    "id": "cust_abc123xyz",
    "name": "Acme University",
    "apiKey": "ck_live_abc123xyz789",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "req_portal003",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}

Delete end customer

delete

Deletes an end customer and immediately revokes their API key.

Warning: This action is irreversible. All subsequent API requests using this customer's key in the X-Customer-Key header will fail with 403 Forbidden.

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Path parameters

customerIdstringRequired

Unique customer identifier. Use sandbox examples below for testing.

Example: {"value":"clx8f2k9h0001qr5tgvwxyz12","summary":"Northern Virginia Community College"}

Responses

204

Customer deleted successfully

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

404

Resource not found

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

delete

/customers/{customerId}

HTTPcURLJavaScriptPython

DELETE /v1/customers/{customerId} HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update end customer

patch

Updates an end customer's name.

Note: The API key is not returned in this response for security. Use GET /customers/{customerId} to retrieve the key.

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Path parameters

customerIdstringRequired

Unique customer identifier. Use sandbox examples below for testing.

Example: {"value":"clx8f2k9h0001qr5tgvwxyz12","summary":"Northern Virginia Community College"}

Body

application/json

namestring · min: 1 · max: 255Optional

New customer name

Example: Acme University - Production

Responses

200

Customer updated successfully

application/json

400

Invalid request parameters

application/json

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

404

Resource not found

application/json

409

Conflict - customer name already exists

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

patch

/customers/{customerId}

HTTPcURLJavaScriptPython

PATCH /v1/customers/{customerId} HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "name": "Acme University - Production"
}

{
  "object": "customer",
  "data": {
    "id": "cust_abc123xyz",
    "name": "Acme University - Production",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "req_portal004",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}

Get customer usage and rate limits

get

Retrieves current rate limit statistics and usage metrics for an end customer.

Use this to monitor customer API usage and proactively manage rate limits.

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Path parameters

customerIdstringRequired

Unique customer identifier. Use sandbox examples below for testing.

Example: {"value":"clx8f2k9h0001qr5tgvwxyz12","summary":"Northern Virginia Community College"}

Responses

200

Customer usage statistics

application/json

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

404

Resource not found

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

get

/customers/{customerId}/usage

HTTPcURLJavaScriptPython

GET /v1/customers/{customerId}/usage HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "customer_usage",
  "data": {
    "customerId": "cust_abc123xyz",
    "rateLimits": {
      "requestsLimit": 1000,
      "requestsThisWindow": 247,
      "windowResetsAt": "2025-01-30T13:00:00Z"
    },
    "usage": {
      "requestsToday": 1523,
      "requestsThisMonth": 34521
    }
  },
  "meta": {
    "requestId": "req_portal005",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}

Rotate customer API key

post

Generates a new API key for an end customer, immediately invalidating the old one.

Warning: The old key is invalidated immediately upon calling this endpoint. Update your integration to use the new key in the X-Customer-Key header before rotating, or be prepared to update immediately after to minimize downtime.

Authentication: Requires only platform API key (no X-Customer-Key header).

Authorizations

bearerAuth

AuthorizationstringRequired

Platform API key passed as a Bearer token in the Authorization header. Use your test key for the testing environment and your production key for production.

Path parameters

customerIdstringRequired

Unique customer identifier. Use sandbox examples below for testing.

Example: {"value":"clx8f2k9h0001qr5tgvwxyz12","summary":"Northern Virginia Community College"}

Responses

200

API key rotated successfully

application/json

401

Missing or invalid API key

application/json

403

Access denied (insufficient permissions or quota exceeded)

application/json

404

Resource not found

application/json

429

Rate limit exceeded

application/json

500

Internal server error

application/json

post

/customers/{customerId}/rotate-key

HTTPcURLJavaScriptPython

POST /v1/customers/{customerId}/rotate-key HTTP/1.1
Host: embedded-api-sandbox.mapademics.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "customer",
  "data": {
    "id": "cust_abc123xyz",
    "name": "Acme University",
    "apiKey": "ck_live_NEW_KEY_xyz789",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "req_portal006",
    "timestamp": "2025-01-30T12:00:00Z"
  }
}