POST
/
v2
/
keys.updateCredits
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.Keys.UpdateCredits(ctx, components.V2KeysUpdateCreditsRequestBody{
        KeyID: "key_2cGKbMxRyIzhCxo1Idjz8q",
        Value: unkey.Int64(1000),
        Operation: components.OperationSet,
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2KeysUpdateCreditsResponseBody != nil {
        // handle response
    }
}
{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "remaining": 1000,
    "refill": {
      "interval": "daily",
      "amount": 1000,
      "refillDay": 15
    }
  }
}

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
​
keyId
string
required

The ID of the key to update (begins with key_). This is the database reference ID for the key, not the actual API key string that users authenticate with. This ID uniquely identifies which key's credits will be updated.

Minimum length: 3
Example:

"key_2cGKbMxRyIzhCxo1Idjz8q"

​
operation
enum<string>
required

Defines how to modify the key's remaining credits. Use 'set' to replace current credits with a specific value or unlimited usage, 'increment' to add credits for plan upgrades or credit purchases, and 'decrement' to reduce credits for refunds or policy violations.

Available options:
set,
increment,
decrement
Example:

"set"

​
value
integer | null

The credit value to use with the specified operation. The meaning depends on the operation: for 'set', this becomes the new remaining credits value; for 'increment', this amount is added to current credits; for 'decrement', this amount is subtracted from current credits.

Set to null when using 'set' operation to make the key unlimited (removes usage restrictions entirely). When decrementing, if the result would be negative, remaining credits are automatically set to zero. Credits are consumed during successful key verification, and when credits reach zero, verification fails with code=INSUFFICIENT_CREDITS.

Required when using 'increment' or 'decrement' operations. Optional for 'set' operation (null creates unlimited usage).

Required range: 0 <= x <= 9223372036854776000
Example:

1000

Response

Credits updated successfully. Response includes updated remaining credits and refill settings.

​
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

Credit configuration and remaining balance for this key.