Update portal

Change a portal’s slug, display name, the resource it serves, its enabled state, or its branding.

Unreleased and subject to change without notice.

Only the fields you send change. Omitting a field leaves it as it is, and for branding, sending null clears it. Send at most one of keyspaceId or appId.

Two changes affect your end users immediately:

Re-pointing at a different resource revokes the portal’s live sessions, because a session carries the scope it was minted with.
Disabling stops new sessions and revokes the live ones. Re-enabling does not restore them.

Required Permissions

Your root key must have one of:

portal.*.update_portal (to update any portal in the workspace)
portal.<portal_id>.update_portal (to update a specific portal)

Without the permission this returns 404, not 403.

POST

portal.updatePortal

Go (SDK)

package main

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

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

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

    res, err := s.Portal.UpdatePortal(ctx, components.V2PortalUpdatePortalRequestBody{
        Portal: "proj_1234abcd",
        Slug: unkey.Pointer("acme-portal"),
        DisplayName: unkey.Pointer("Acme"),
        KeyspaceID: unkey.Pointer("ks_1234abcd"),
        AppID: unkey.Pointer("app_1234abcd"),
        Enabled: unkey.Pointer(false),
        LogoURL: optionalnullable.From(unkey.Pointer("https://cdn.example.com/logo.svg")),
        PrimaryColor: optionalnullable.From(unkey.Pointer("#6366f1")),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2PortalUpdatePortalResponseBody != nil {
        // handle response
    }
}

from unkey.py import Unkey


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.portal.update_portal(portal="proj_1234abcd", slug="acme-portal", display_name="Acme", keyspace_id="ks_1234abcd", app_id="app_1234abcd", enabled=False, logo_url="https://cdn.example.com/logo.svg", primary_color="#6366f1")

    # Handle response
    print(res)

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

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.portal.updatePortal({
    portal: "proj_1234abcd",
    slug: "acme-portal",
    displayName: "Acme",
    keyspaceId: "ks_1234abcd",
    appId: "app_1234abcd",
    enabled: false,
    logoUrl: "https://cdn.example.com/logo.svg",
    primaryColor: "#6366f1",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/portal.updatePortal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "portal": "proj_1234abcd",
  "slug": "acme-portal",
  "displayName": "Acme",
  "keyspaceId": "ks_1234abcd",
  "appId": "app_1234abcd",
  "enabled": false,
  "logoUrl": "https://cdn.example.com/logo.svg",
  "primaryColor": "#6366f1"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    portal: 'proj_1234abcd',
    slug: 'acme-portal',
    displayName: 'Acme',
    keyspaceId: 'ks_1234abcd',
    appId: 'app_1234abcd',
    enabled: false,
    logoUrl: 'https://cdn.example.com/logo.svg',
    primaryColor: '#6366f1'
  })
};

fetch('https://api.unkey.com/v2/portal.updatePortal', 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.updatePortal",
  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([
    'portal' => 'proj_1234abcd',
    'slug' => 'acme-portal',
    'displayName' => 'Acme',
    'keyspaceId' => 'ks_1234abcd',
    'appId' => 'app_1234abcd',
    'enabled' => false,
    'logoUrl' => 'https://cdn.example.com/logo.svg',
    'primaryColor' => '#6366f1'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.updatePortal")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"portal\": \"proj_1234abcd\",\n  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": false,\n  \"logoUrl\": \"https://cdn.example.com/logo.svg\",\n  \"primaryColor\": \"#6366f1\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"portal\": \"proj_1234abcd\",\n  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": false,\n  \"logoUrl\": \"https://cdn.example.com/logo.svg\",\n  \"primaryColor\": \"#6366f1\"\n}"

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

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "pc_1234abcd",
    "slug": "acme-portal",
    "displayName": "Acme",
    "enabled": true,
    "createdAt": 1719849600000,
    "keyspaceId": "ks_1234abcd",
    "appId": "app_1234abcd",
    "branding": {
      "logoUrl": "https://cdn.example.com/logo.svg",
      "primaryColor": "#6366f1"
    },
    "updatedAt": 1719936000000
  }
}

{
  "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

Authorization

string

header

required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token 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. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. 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

portal

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

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

Example:

"proj_1234abcd"

slug

string

New handle for this portal. Omit to leave unchanged.

Required string length: 3 - 64

Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

Example:

"acme-portal"

displayName

string

New human-readable name shown to your end users. Omit to leave unchanged.

Required string length: 1 - 64

Pattern: ^\S(.*\S)?$

Example:

"Acme"

keyspaceId

string

Re-point the portal at a different keyspace. Omit to leave the resource it serves alone.

Re-pointing revokes the portal's live sessions, because a session carries the keyspace scope it was minted with and would otherwise keep reaching the resource the portal no longer serves.

The new keyspace must belong to the same project as the portal's current resource. A portal cannot move between projects, because its permissions are addressed under the project it belongs to. Re-pointing across projects returns 412; create a portal in the target project instead.

Required string length: 1 - 255

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

Example:

"ks_1234abcd"

appId

string

Re-point the portal at a different app. Omit to leave the resource it serves alone.

Re-pointing revokes the portal's live sessions, for the same reason as keyspaceId.

The same project restriction applies, and it is easy to hit when switching between an app and a keyspace: keyspaces are created in the workspace's default project, while an app belongs to the project you created it in.

Required string length: 1 - 255

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

Example:

"app_1234abcd"

enabled

boolean

Whether new sessions can be minted. Omit to leave unchanged.

Disabling also revokes the portal's live sessions. Re-enabling does not restore them.

Example:

false

logoUrl

string<uri> | null

Absolute https:// URL of the portal logo. Omit to leave unchanged, or set null to remove the logo.

Required string length: 1 - 500

Pattern: ^https://

Example:

"https://cdn.example.com/logo.svg"

primaryColor

string | null

Six-digit hex colour for primary actions. Omit to leave unchanged, or set null to fall back to default styling.

Pattern: ^#[0-9a-fA-F]{6}$

Example:

"#6366f1"

Response

The portal as it now stands.

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

A portal you expose to your end users so they can manage their own keys.

Exactly one of keyspaceId or appId is present, naming the single resource the portal serves. Neither is in the required list because which one appears depends on the portal, so a reader checks for the one it cares about.

Show child attributes

⌘I

Go (SDK)

package main

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

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

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

    res, err := s.Portal.UpdatePortal(ctx, components.V2PortalUpdatePortalRequestBody{
        Portal: "proj_1234abcd",
        Slug: unkey.Pointer("acme-portal"),
        DisplayName: unkey.Pointer("Acme"),
        KeyspaceID: unkey.Pointer("ks_1234abcd"),
        AppID: unkey.Pointer("app_1234abcd"),
        Enabled: unkey.Pointer(false),
        LogoURL: optionalnullable.From(unkey.Pointer("https://cdn.example.com/logo.svg")),
        PrimaryColor: optionalnullable.From(unkey.Pointer("#6366f1")),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2PortalUpdatePortalResponseBody != nil {
        // handle response
    }
}

from unkey.py import Unkey


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.portal.update_portal(portal="proj_1234abcd", slug="acme-portal", display_name="Acme", keyspace_id="ks_1234abcd", app_id="app_1234abcd", enabled=False, logo_url="https://cdn.example.com/logo.svg", primary_color="#6366f1")

    # Handle response
    print(res)

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

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.portal.updatePortal({
    portal: "proj_1234abcd",
    slug: "acme-portal",
    displayName: "Acme",
    keyspaceId: "ks_1234abcd",
    appId: "app_1234abcd",
    enabled: false,
    logoUrl: "https://cdn.example.com/logo.svg",
    primaryColor: "#6366f1",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/portal.updatePortal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "portal": "proj_1234abcd",
  "slug": "acme-portal",
  "displayName": "Acme",
  "keyspaceId": "ks_1234abcd",
  "appId": "app_1234abcd",
  "enabled": false,
  "logoUrl": "https://cdn.example.com/logo.svg",
  "primaryColor": "#6366f1"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    portal: 'proj_1234abcd',
    slug: 'acme-portal',
    displayName: 'Acme',
    keyspaceId: 'ks_1234abcd',
    appId: 'app_1234abcd',
    enabled: false,
    logoUrl: 'https://cdn.example.com/logo.svg',
    primaryColor: '#6366f1'
  })
};

fetch('https://api.unkey.com/v2/portal.updatePortal', 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.updatePortal",
  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([
    'portal' => 'proj_1234abcd',
    'slug' => 'acme-portal',
    'displayName' => 'Acme',
    'keyspaceId' => 'ks_1234abcd',
    'appId' => 'app_1234abcd',
    'enabled' => false,
    'logoUrl' => 'https://cdn.example.com/logo.svg',
    'primaryColor' => '#6366f1'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.updatePortal")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"portal\": \"proj_1234abcd\",\n  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": false,\n  \"logoUrl\": \"https://cdn.example.com/logo.svg\",\n  \"primaryColor\": \"#6366f1\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"portal\": \"proj_1234abcd\",\n  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": false,\n  \"logoUrl\": \"https://cdn.example.com/logo.svg\",\n  \"primaryColor\": \"#6366f1\"\n}"

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

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "pc_1234abcd",
    "slug": "acme-portal",
    "displayName": "Acme",
    "enabled": true,
    "createdAt": 1719849600000,
    "keyspaceId": "ks_1234abcd",
    "appId": "app_1234abcd",
    "branding": {
      "logoUrl": "https://cdn.example.com/logo.svg",
      "primaryColor": "#6366f1"
    },
    "updatedAt": 1719936000000
  }
}

{
  "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"
  }
}

Compute

API management

Update portal

Authorizations

Body

Response