Create portal session

Create a portal session for an end user and get the URL to redirect them to.

The URL carries a single-use exchange code valid for 15 minutes, which the portal redeems exactly once for a 24-hour access token via portal.exchangeCode.

Required Permissions

Authorization runs in two stages, and both must pass.

First, your root key must have one of the following permissions:

portal.*.create_portal_session (to mint sessions for any portal in the workspace)
portal.<portal_id>.create_portal_session (to mint sessions for a specific portal)

Second, a session can never carry a capability your root key does not itself hold. Each requested scope additionally requires the equivalent permission on every keyspace the portal resolves to:

keys:read requires api.<api_id>.read_key and api.<api_id>.read_api
keys:reroll requires api.<api_id>.create_key, plus api.<api_id>.encrypt_key when the keyspace stores encrypted keys
analytics:read requires api.<api_id>.read_analytics

The * form of each is also accepted. Requesting a scope you do not hold returns 403 for the whole request rather than minting a reduced session, so a missing grant is visible instead of surfacing later as a broken portal.

Missing the portal permission itself returns 404, not 403: a caller who cannot mint for a portal is not told whether it exists.

Your root key must also be associated with a workspace that has an enabled portal.

POST

portal.createSession

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.CreateSession(ctx, components.V2PortalCreateSessionRequestBody{
        Portal: "proj_1234abcd",
        ExternalID: "user_123",
        Scopes: []components.Scope{
            components.ScopeKeysRead,
            components.ScopeKeysReroll,
            components.ScopeAnalyticsRead,
        },
        ReturnURL: unkey.Pointer("https://app.example.com/settings/api-keys"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2PortalCreateSessionResponseBody != nil {
        // handle response
    }
}

from unkey.py import Unkey, models


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

    res = unkey.portal.create_session(portal="proj_1234abcd", external_id="user_123", scopes=[
        models.Scope.KEYS_READ,
        models.Scope.KEYS_REROLL,
        models.Scope.ANALYTICS_READ,
    ], return_url="https://app.example.com/settings/api-keys")

    # 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.createSession({
    portal: "proj_1234abcd",
    externalId: "user_123",
    scopes: [
      "keys:read",
      "keys:reroll",
      "analytics:read",
    ],
    returnUrl: "https://app.example.com/settings/api-keys",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/portal.createSession \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "portal": "proj_1234abcd",
  "externalId": "user_123",
  "scopes": [
    "keys:read",
    "keys:reroll"
  ],
  "returnUrl": "https://app.example.com/settings/api-keys"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    portal: 'proj_1234abcd',
    externalId: 'user_123',
    scopes: ['keys:read', 'keys:reroll'],
    returnUrl: 'https://app.example.com/settings/api-keys'
  })
};

fetch('https://api.unkey.com/v2/portal.createSession', 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.createSession",
  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',
    'externalId' => 'user_123',
    'scopes' => [
        'keys:read',
        'keys:reroll'
    ],
    'returnUrl' => 'https://app.example.com/settings/api-keys'
  ]),
  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.createSession")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"portal\": \"proj_1234abcd\",\n  \"externalId\": \"user_123\",\n  \"scopes\": [\n    \"keys:read\",\n    \"keys:reroll\"\n  ],\n  \"returnUrl\": \"https://app.example.com/settings/api-keys\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"externalId\": \"user_123\",\n  \"scopes\": [\n    \"keys:read\",\n    \"keys:reroll\"\n  ],\n  \"returnUrl\": \"https://app.example.com/settings/api-keys\"\n}"

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

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "ps_abc123def456",
    "url": "https://portal.unkey.com/?code=pec_abc123def456"
  }
}

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

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"

externalId

string

required

The end user's identifier in the customer's system. Accepts arbitrary string values (user IDs, emails, UUIDs, etc.).

Required string length: 1 - 256

Example:

"user_123"

scopes

enum<string>[]

required

The capabilities granted to the end user in the Portal, from a fixed vocabulary. All capabilities are scoped to this end user: key capabilities (keys:*) apply only to keys the end user owns within the keyspace configured on the portal. An end user can never see another identity's keys.

Rerolling and usage analytics are both reached from the keys page, so keys:reroll and analytics:read each require keys:read in the same session; requesting either without it is rejected.

Each scope requires the equivalent permission on your own root key. See Required Permissions on this operation.

Minimum array length: 1

Available options:

keys:read,

keys:reroll,

analytics:read

Example:

["keys:read", "keys:reroll"]

returnUrl

string<uri>

Absolute URL the end user is sent back to when they leave the portal, or when their session expires mid-visit. Set per session rather than per portal, so one portal can serve several entry points and return each user to the page they came from.

When omitted, the portal shows no return link.

Maximum string length: 500

Example:

"https://app.example.com/settings/api-keys"

Response

Session created successfully. Redirect the end user to the returned URL.

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.CreateSession(ctx, components.V2PortalCreateSessionRequestBody{
        Portal: "proj_1234abcd",
        ExternalID: "user_123",
        Scopes: []components.Scope{
            components.ScopeKeysRead,
            components.ScopeKeysReroll,
            components.ScopeAnalyticsRead,
        },
        ReturnURL: unkey.Pointer("https://app.example.com/settings/api-keys"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2PortalCreateSessionResponseBody != nil {
        // handle response
    }
}

from unkey.py import Unkey, models


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

    res = unkey.portal.create_session(portal="proj_1234abcd", external_id="user_123", scopes=[
        models.Scope.KEYS_READ,
        models.Scope.KEYS_REROLL,
        models.Scope.ANALYTICS_READ,
    ], return_url="https://app.example.com/settings/api-keys")

    # 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.createSession({
    portal: "proj_1234abcd",
    externalId: "user_123",
    scopes: [
      "keys:read",
      "keys:reroll",
      "analytics:read",
    ],
    returnUrl: "https://app.example.com/settings/api-keys",
  });

  console.log(result);
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/portal.createSession \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "portal": "proj_1234abcd",
  "externalId": "user_123",
  "scopes": [
    "keys:read",
    "keys:reroll"
  ],
  "returnUrl": "https://app.example.com/settings/api-keys"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    portal: 'proj_1234abcd',
    externalId: 'user_123',
    scopes: ['keys:read', 'keys:reroll'],
    returnUrl: 'https://app.example.com/settings/api-keys'
  })
};

fetch('https://api.unkey.com/v2/portal.createSession', 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.createSession",
  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',
    'externalId' => 'user_123',
    'scopes' => [
        'keys:read',
        'keys:reroll'
    ],
    'returnUrl' => 'https://app.example.com/settings/api-keys'
  ]),
  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.createSession")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"portal\": \"proj_1234abcd\",\n  \"externalId\": \"user_123\",\n  \"scopes\": [\n    \"keys:read\",\n    \"keys:reroll\"\n  ],\n  \"returnUrl\": \"https://app.example.com/settings/api-keys\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"externalId\": \"user_123\",\n  \"scopes\": [\n    \"keys:read\",\n    \"keys:reroll\"\n  ],\n  \"returnUrl\": \"https://app.example.com/settings/api-keys\"\n}"

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

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "id": "ps_abc123def456",
    "url": "https://portal.unkey.com/?code=pec_abc123def456"
  }
}

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

Authorizations

Body

Response