Skip to main content
POST
/
v2
/
apis.listKeys
Go (SDK)
package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Apis.ListKeys(ctx, components.V2ApisListKeysRequestBody{
        APIID: "api_1234abcd",
        Cursor: unkey.Pointer("key_1234abcd"),
        ExternalID: unkey.Pointer("user_1234abcd"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2ApisListKeysResponseBody != nil {
        // handle response
    }
}
{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "keyId": "key_1234567890abcdef",
      "start": "sk_test_abc123",
      "enabled": true,
      "createdAt": 1701425400000,
      "name": "Production API Key",
      "meta": null,
      "updatedAt": 1701425400000,
      "expires": 1735689600000,
      "permissions": [
        "documents.read",
        "documents.write"
      ],
      "roles": [
        "editor",
        "viewer"
      ],
      "identity": {
        "id": "<string>",
        "externalId": "<string>",
        "meta": {},
        "ratelimits": [
          {
            "id": "rl_1234567890abcdef",
            "name": "api_requests",
            "limit": 1000,
            "duration": 3600000,
            "autoApply": true
          }
        ]
      },
      "plaintext": "sk_test_abc123def456",
      "ratelimits": [
        {
          "id": "rl_1234567890abcdef",
          "name": "api_requests",
          "limit": 1000,
          "duration": 3600000,
          "autoApply": true
        }
      ],
      "keyCredits": {
        "remaining": 1000,
        "refill": {
          "interval": "daily",
          "amount": 1000,
          "refillDay": 15
        }
      }
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ=="
  }
}

Authorizations

​
Authorization
string
header
required

Unkey uses API keys (root keys) for authentication. These keys authorize access to management operations in the API. To authenticate, include your root key in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Key permissions follow a hierarchical structure with patterns like resource.resource_id.action (e.g., apis.*.create_key, apis.*.read_api). Security best practices:

  • Keep root keys secure and never expose them in client-side code
  • Use different root keys for different environments
  • Rotate keys periodically, especially after team member departures
  • Create keys with minimal necessary permissions following least privilege principle
  • Monitor key usage with audit logs.

Body

application/json
​
apiId
string
required

The API namespace whose keys you want to list. Returns all keys in this API, subject to pagination and filters.

Minimum string length: 1
Example:

"api_1234abcd"

​
limit
integer
default:100

Maximum number of keys to return per request. Balance between response size and number of pagination calls needed.

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor from previous response to fetch next page. Use when hasMore: true in previous response.

Example:

"key_1234abcd"

​
externalId
string

Filter keys by external ID to find keys for a specific user or entity. Must exactly match the externalId set during key creation.

Minimum string length: 1
Example:

"user_1234abcd"

​
decrypt
boolean
default:false

When true, attempts to include the plaintext key value in the response. SECURITY WARNING:

  • This requires special permissions on the calling root key
  • Only works for keys created with 'recoverable: true'
  • Exposes sensitive key material in the response
  • Should only be used in secure administrative contexts
  • Never enable this in user-facing applications
​
revalidateKeysCache
boolean
default:false

EXPERIMENTAL: Skip the cache and fetch the keys directly from the database. This ensures you see the most recent state, including keys created moments ago. Use this when:

  • You've just created a key and need to display it immediately
  • You need absolute certainty about the current key state
  • You're debugging cache consistency issues

This parameter comes with a performance cost and should be used sparingly.

Response

Successfully retrieved paginated keys. Use the pagination cursor for additional results when hasMore: true.

​
meta
object
required

Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The requestId is particularly important when troubleshooting issues with the Unkey support team.

​
data
object[]
required

Array of API keys with complete configuration and metadata.

Maximum array length: 100
​
pagination
object

Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.