Create portal

Create a portal for one app or keyspace in your workspace.

Unreleased and subject to change without notice.

Send exactly one of keyspaceId or appId. That resource must belong to your workspace, and it can back only one portal, so a second portal for the same resource is a 409.

displayName is what your end users see. It is yours to set and change independently of the resource the portal serves.

Required Permissions

Your root key must have portal.*.create_portal. A grant scoped to a specific portal id does not authorize creation, because the id does not exist yet.

POST

portal.createPortal

Go (SDK)

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v3"
	"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.CreatePortal(ctx, components.CreateV2PortalCreatePortalRequestBodyUnionV2PortalCreatePortalRequestBody1(
        components.V2PortalCreatePortalRequestBody1{
            Slug: "acme-portal",
            DisplayName: "Acme",
            KeyspaceID: "ks_1234abcd",
            AppID: unkey.Pointer("app_1234abcd"),
            LogoURL: unkey.Pointer("https://cdn.example.com/logo.svg"),
            PrimaryColor: unkey.Pointer("#6366f1"),
        },
    ))
    if err != nil {
        log.Fatal(err)
    }
    if res.V2PortalCreatePortalResponseBody != nil {
        // handle response
    }
}

from unkey.py import Unkey


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

    res = unkey.portal.create_portal(request={
        "slug": "acme-portal",
        "display_name": "Acme",
        "keyspace_id": "ks_1234abcd",
        "app_id": "app_1234abcd",
        "enabled": True,
        "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.createPortal({
    slug: "acme-portal",
    displayName: "Acme",
    keyspaceId: "ks_1234abcd",
    appId: "app_1234abcd",
    enabled: true,
    logoUrl: "https://cdn.example.com/logo.svg",
    primaryColor: "#6366f1",
  });

  console.log(result);
}

run();

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

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

fetch('https://api.unkey.com/v2/portal.createPortal', 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.createPortal",
  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([
    'slug' => 'acme-portal',
    'displayName' => 'Acme',
    'keyspaceId' => 'ks_1234abcd',
    'appId' => 'app_1234abcd',
    'enabled' => true,
    '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.createPortal")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": true,\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.createPortal")

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  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": true,\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": {
    "portalId": "prt_1234abcd"
  }
}

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

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

Option 1
Option 2

slug

string

required

URL-safe handle for this portal, unique within your workspace. Lowercase alphanumerics and single hyphens, 3-64 characters, not starting or ending with a hyphen.

Required string length: 3 - 64

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

Example:

"acme-portal"

displayName

string

required

Human-readable name your end users see in the portal header and page titles. Unlike slug it is not part of any URL, so it can be changed freely.

Required string length: 1 - 64

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

Example:

"Acme"

keyspaceId

string

required

The id of the keyspace this portal serves keys for. Must belong to your workspace.

A portal serves exactly one resource, so keyspaceId and appId are mutually exclusive.

Required string length: 1 - 255

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

Example:

"ks_1234abcd"

appId

string

The id of the app this portal serves keys for. Must belong to your workspace.

A portal serves exactly one resource, so appId and keyspaceId are mutually exclusive.

Required string length: 1 - 255

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

Example:

"app_1234abcd"

enabled

boolean

default:true

Whether sessions can be minted for this portal immediately. Defaults to true; send false to create it dormant and enable it later.

Example:

true

logoUrl

string<uri>

Absolute https:// URL of the logo shown in the portal header.

Loaded by your end users' browsers, so the host you name receives their IP and user agent on every page view.

Required string length: 1 - 500

Pattern: ^https://

Example:

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

primaryColor

string

Six-digit hex colour used for primary actions and accents in the portal.

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

Example:

"#6366f1"

Response

Portal created successfully.

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

⌘I

Go (SDK)

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v3"
	"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.CreatePortal(ctx, components.CreateV2PortalCreatePortalRequestBodyUnionV2PortalCreatePortalRequestBody1(
        components.V2PortalCreatePortalRequestBody1{
            Slug: "acme-portal",
            DisplayName: "Acme",
            KeyspaceID: "ks_1234abcd",
            AppID: unkey.Pointer("app_1234abcd"),
            LogoURL: unkey.Pointer("https://cdn.example.com/logo.svg"),
            PrimaryColor: unkey.Pointer("#6366f1"),
        },
    ))
    if err != nil {
        log.Fatal(err)
    }
    if res.V2PortalCreatePortalResponseBody != nil {
        // handle response
    }
}

from unkey.py import Unkey


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

    res = unkey.portal.create_portal(request={
        "slug": "acme-portal",
        "display_name": "Acme",
        "keyspace_id": "ks_1234abcd",
        "app_id": "app_1234abcd",
        "enabled": True,
        "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.createPortal({
    slug: "acme-portal",
    displayName: "Acme",
    keyspaceId: "ks_1234abcd",
    appId: "app_1234abcd",
    enabled: true,
    logoUrl: "https://cdn.example.com/logo.svg",
    primaryColor: "#6366f1",
  });

  console.log(result);
}

run();

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

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

fetch('https://api.unkey.com/v2/portal.createPortal', 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.createPortal",
  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([
    'slug' => 'acme-portal',
    'displayName' => 'Acme',
    'keyspaceId' => 'ks_1234abcd',
    'appId' => 'app_1234abcd',
    'enabled' => true,
    '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.createPortal")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": true,\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.createPortal")

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  \"slug\": \"acme-portal\",\n  \"displayName\": \"Acme\",\n  \"keyspaceId\": \"ks_1234abcd\",\n  \"appId\": \"app_1234abcd\",\n  \"enabled\": true,\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": {
    "portalId": "prt_1234abcd"
  }
}

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

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

APIs

Keys

Identities

Permissions

Rate limiting

Analytics

Portal

Create portal

Authorizations

Body

Response