On this page

API Keys

Create and manage API keys programmatically. Keys can only be viewed once at creation.

Last updated · Sergio Xalambrí

Manage API keys for your team programmatically. Each team can have a maximum of 10 API keys.

GET /api/v1/api-keys

Returns the API keys for your team. The key values themselves stay with you from creation; a listing carries the prefix, which is enough to identify a key.

This list is paginated. See Pagination for following the Link header to the next page.

Required scope: api-keys:read

Query Parameters

  • perPageinteger

    Results per page, 1-200 (default: 50)

  • cursorstring

    Page to fetch, taken from a Link header

Response Fields

  • data.apiKeysarray

    One page of API keys

  • data.apiKeys[].idstring

    Unique identifier for the API key

  • data.apiKeys[].namestring

    Display name of the API key

  • data.apiKeys[].scopesarray

    List of permission scopes granted to this key

  • data.apiKeys[].createdAtinteger

    Unix timestamp in milliseconds of the creation

  • data.apiKeys[].lastUsedAtinteger | null

    Unix timestamp in milliseconds of the last use

  • data.apiKeys[].expiresAtinteger | null

    Unix timestamp in milliseconds of the expiration

  • data.apiKeys[].keyPrefixstring

    First 15 characters of the key, for identification

  • meta.requestIdstring

    Identifier for this request

  • meta.timestampstring

    ISO 8601 timestamp of the response

  • meta.pagination.nextstring | null

    Cursor for the following page, null on the last

  • meta.pagination.prevstring | null

    Cursor for the preceding page, null on the first

  • meta.pagination.perPageinteger

    Results this page was built with

  • meta.pagination.totalinteger

    API keys matching, across every page

Errors (3)
StatusTypeMeaning
400bad-requestThe request is malformed
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • apiKeysApiKey[]Required
      Show nested fields
      • idstringRequired
      • namestringRequired
      • scopesstring[]Required
      • createdAtintegerRequired

        Epoch milliseconds

      • lastUsedAtinteger | nullRequired

        Epoch milliseconds

      • expiresAtinteger | nullRequired

        Null for a key that never expires

      • keyPrefixstringRequired

        The key's first characters, to recognize it

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

    • paginationobjectRequired
      Show nested fields
      • nextstring | nullRequired

        Cursor of the following page

      • prevstring | nullRequired

        Cursor of the preceding page

      • perPageintegerRequired
      • totalinteger

cURL

Terminal
curl -i "https://uptime.sergiodxa.com/api/v1/api-keys?perPage=100" \
  -H "Authorization: Bearer uptime_your_api_key"

Response

json
{
	"data": {
		"apiKeys": [
			{
				"id": "key_abc123",
				"name": "Production Integration",
				"scopes": ["monitors:read", "monitors:write"],
				"createdAt": 1768467600000,
				"lastUsedAt": 1771065000000,
				"expiresAt": null,
				"keyPrefix": "uptime_a1b2c3d4"
			},
			{
				"id": "key_def456",
				"name": "CI/CD Pipeline",
				"scopes": ["monitors:read"],
				"createdAt": 1770301320000,
				"lastUsedAt": null,
				"expiresAt": 1785974400000,
				"keyPrefix": "uptime_d4e5f6a7"
			}
		]
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z",
		"pagination": {
			"next": null,
			"prev": null,
			"perPage": 100,
			"total": 2
		}
	}
}

POST /api/v1/api-keys

Creates a new API key for your team and answers 201 Created. A key can grant only scopes it holds itself.

Required scope: api-keys:write

Request Body

  • namestringRequired

    Display name for the key (1-255 characters)

  • scopesarrayRequired

    Permission scopes to grant (at least one required)

  • expiresAtstring

    Date/time for key expiration (e.g. ISO 8601)

Response Fields

  • data.apiKey.idstring

    Unique identifier for the API key

  • data.apiKey.namestring

    Display name of the API key

  • data.apiKey.scopesarray

    List of permission scopes granted to this key

  • data.apiKey.createdAtinteger

    Unix timestamp in milliseconds of the creation

  • data.apiKey.lastUsedAtinteger | null

    Always null for newly created keys

  • data.apiKey.expiresAtinteger | null

    Unix timestamp in milliseconds of the expiration, null for none

  • data.apiKey.keyPrefixstring

    First 15 characters of the key, for identification

  • data.keystring

    The full API key value. Only returned once at creation.

  • meta.requestIdstring

    Identifier for this request

  • meta.timestampstring

    ISO 8601 timestamp of the response

Errors (6)
StatusTypeMeaning
400validation-errorThe request failed validation
400limit-exceededThe team has reached its limit for this resource
400idempotency-key-invalidThe Idempotency-Key header is not valid
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
409idempotency-key-in-useA request with this idempotency key is still being processed
Response fields (201)
  • dataobjectRequired
    Show nested fields
    • apiKeyobjectRequired
      Show nested fields
      • idstringRequired
      • namestringRequired
      • scopesstring[]Required
      • createdAtintegerRequired

        Epoch milliseconds

      • lastUsedAtinteger | nullRequired

        Epoch milliseconds

      • expiresAtinteger | nullRequired

        Null for a key that never expires

      • keyPrefixstringRequired

        The key's first characters, to recognize it

    • keystringRequired

      The secret, shown only in this response

  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl -X POST https://uptime.sergiodxa.com/api/v1/api-keys \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions",
    "scopes": ["monitors:read", "monitors:write"],
    "expiresAt": "2027-02-14T00:00:00Z"
  }'
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/api-keys", {
	method: "POST",
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		"name": "GitHub Actions",
		"scopes": [
			"monitors:read",
			"monitors:write"
		],
		"expiresAt": "2027-02-14T00:00:00Z"
	}),
});
let result = await response.json();

Response

json
{
	"data": {
		"apiKey": {
			"id": "key_ghi789",
			"name": "GitHub Actions",
			"scopes": ["monitors:read", "monitors:write"],
			"createdAt": 1771066800000,
			"lastUsedAt": null,
			"expiresAt": 1802563200000,
			"keyPrefix": "uptime_9f8e7d6c"
		},
		"key": "uptime_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0"
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T11:00:00.000Z"
	}
}

DELETE /api/v1/api-keys/:id

Permanently deletes an API key. This action cannot be undone. Any integrations using this key will immediately lose access.

Required scope: api-keys:write

Path Parameters

  • idstring

    The unique identifier of the API key to delete

Response Fields

  • data.deletedboolean

    Always true on successful deletion

Errors (4)
StatusTypeMeaning
400validation-errorThe request failed validation
401unauthorizedThe API key is missing or invalid
403forbiddenThe API key lacks the required scope
404not-foundThe resource does not exist
Response fields (200)
  • dataobjectRequired
    Show nested fields
    • deletedtrueRequired
  • metaobjectRequired
    Show nested fields
    • requestIdstringRequired

      Format: uuid.

    • timestampstringRequired

      Format: date-time.

cURL

Terminal
curl -X DELETE https://uptime.sergiodxa.com/api/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"
request.js
let response = await fetch("https://uptime.sergiodxa.com/api/v1/api-keys/key_abc123", {
	method: "DELETE",
	headers: {
		"Authorization": "Bearer uptime_your_api_key",
	},
});
let result = await response.json();

Response

json
{
	"data": {
		"deleted": true
	},
	"meta": {
		"requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
		"timestamp": "2026-02-14T12:00:00.000Z"
	}
}
Documentation