Reroll portal key - Unkey Docs

POST

portal.rerollKey

Python (SDK)

from unkey.py import Unkey, models


with Unkey() as unkey:

    res = unkey.portal.reroll_key(security=models.PortalRerollKeySecurity(
        portal_session="<YOUR_API_KEY_HERE>",
    ), key_id="key_2cGKbMxRyIzhCxo1Idjz8q", expiration=86400000)

    # Handle response
    print(res)

import { Unkey } from "@unkey/api";

const unkey = new Unkey();

async function run() {
  const result = await unkey.portal.rerollKey({
    portalSession: process.env["UNKEY_PORTAL_SESSION"] ?? "",
  }, {
    keyId: "key_2cGKbMxRyIzhCxo1Idjz8q",
    expiration: 86400000,
  });

  console.log(result);
}

run();

package main

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

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

    s := unkey.New()

    res, err := s.Portal.RerollKey(ctx, components.V2KeysRerollKeyRequestBody{
        KeyID: "key_2cGKbMxRyIzhCxo1Idjz8q",
        Expiration: 86400000,
    }, operations.PortalRerollKeySecurity{
        PortalSession: os.Getenv("UNKEY_PORTAL_SESSION"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2KeysRerollKeyResponseBody != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.unkey.com/v2/portal.rerollKey \
  --header 'Content-Type: application/json' \
  --cookie portal_session= \
  --data '
{
  "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
  "expiration": 86400000
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'portal_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({keyId: 'key_2cGKbMxRyIzhCxo1Idjz8q', expiration: 86400000})
};

fetch('https://api.unkey.com/v2/portal.rerollKey', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/portal.rerollKey",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'keyId' => 'key_2cGKbMxRyIzhCxo1Idjz8q',
    'expiration' => 86400000
  ]),
  CURLOPT_COOKIE => "portal_session=",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/portal.rerollKey")
  .header("cookie", "portal_session=")
  .header("Content-Type", "application/json")
  .body("{\n  \"keyId\": \"key_2cGKbMxRyIzhCxo1Idjz8q\",\n  \"expiration\": 86400000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/portal.rerollKey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["cookie"] = 'portal_session='
request["Content-Type"] = 'application/json'
request.body = "{\n  \"keyId\": \"key_2cGKbMxRyIzhCxo1Idjz8q\",\n  \"expiration\": 86400000\n}"

response = http.request(request)
puts response.read_body

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

Authorizations

portal_session

string

required

Browser session cookie for the Customer Portal. Set by portal.exchangeSession and sent automatically by the browser on portal.* requests. Portal sessions are scoped to a single end user (external identity) and can only access the portal.* routes.

Body

application/json

keyId

string

required

The database identifier of the key to reroll.

This is the unique ID returned when creating or listing keys, NOT the actual API key token. You can find this ID in:

The response from keys.createKey
Key verification responses
The Unkey dashboard
API key listing endpoints

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_]+$

Example:

"key_2cGKbMxRyIzhCxo1Idjz8q"

expiration

integer<int64>

required

Duration in milliseconds until the ORIGINAL key is revoked, starting from now.

This parameter controls the overlap period for key rotation:

Set to 0 to revoke the original key immediately
Positive values keep the original key active for the specified duration
Allows graceful migration by giving users time to update their credentials

Common overlap periods:

Immediate revocation: 0
1 hour grace period: 3600000
24 hours grace period: 86400000
7 days grace period: 604800000
30 days grace period: 2592000000

Required range: 0 <= x <= 4102444800000

Example:

86400000

Response

Key rerolled successfully. The new plaintext key is returned exactly once.

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.

Show child attributes

data

object

required

Show child attributes

Last modified on July 23, 2026

Create projectCreate a project to group deployments and applications under a workspace-scoped slug. The slug you provide is the stable, caller-defined handle used to reference this project in subsequent operations (get, update, delete). It must be unique within your workspace. **Important**: The slug cannot collide with an existing project in your workspace. A duplicate slug returns a 409 conflict. **Required Permissions** Your root key must have the following permission: - `project.*.create_project` (to create projects in your workspace)

⌘I

Python (SDK)

from unkey.py import Unkey, models


with Unkey() as unkey:

    res = unkey.portal.reroll_key(security=models.PortalRerollKeySecurity(
        portal_session="<YOUR_API_KEY_HERE>",
    ), key_id="key_2cGKbMxRyIzhCxo1Idjz8q", expiration=86400000)

    # Handle response
    print(res)

import { Unkey } from "@unkey/api";

const unkey = new Unkey();

async function run() {
  const result = await unkey.portal.rerollKey({
    portalSession: process.env["UNKEY_PORTAL_SESSION"] ?? "",
  }, {
    keyId: "key_2cGKbMxRyIzhCxo1Idjz8q",
    expiration: 86400000,
  });

  console.log(result);
}

run();

package main

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

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

    s := unkey.New()

    res, err := s.Portal.RerollKey(ctx, components.V2KeysRerollKeyRequestBody{
        KeyID: "key_2cGKbMxRyIzhCxo1Idjz8q",
        Expiration: 86400000,
    }, operations.PortalRerollKeySecurity{
        PortalSession: os.Getenv("UNKEY_PORTAL_SESSION"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2KeysRerollKeyResponseBody != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.unkey.com/v2/portal.rerollKey \
  --header 'Content-Type: application/json' \
  --cookie portal_session= \
  --data '
{
  "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
  "expiration": 86400000
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'portal_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({keyId: 'key_2cGKbMxRyIzhCxo1Idjz8q', expiration: 86400000})
};

fetch('https://api.unkey.com/v2/portal.rerollKey', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/portal.rerollKey",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'keyId' => 'key_2cGKbMxRyIzhCxo1Idjz8q',
    'expiration' => 86400000
  ]),
  CURLOPT_COOKIE => "portal_session=",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/portal.rerollKey")
  .header("cookie", "portal_session=")
  .header("Content-Type", "application/json")
  .body("{\n  \"keyId\": \"key_2cGKbMxRyIzhCxo1Idjz8q\",\n  \"expiration\": 86400000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/portal.rerollKey")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["cookie"] = 'portal_session='
request["Content-Type"] = 'application/json'
request.body = "{\n  \"keyId\": \"key_2cGKbMxRyIzhCxo1Idjz8q\",\n  \"expiration\": 86400000\n}"

response = http.request(request)
puts response.read_body

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q",
    "key": "prod_2cGKbMxRjIzhCxo1IdjH3arELti7Sdyc8w6XYbvtcyuBowPT"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}