# Manage proxy keys

> Create, rename, replace, and revoke keys.
>
> Web page: https://ports.io/docs/reference/key-lifecycle/
> Documentation index: https://ports.io/llms.txt

Create a named proxy key for an application, copy its secret once, and use it as the proxy password. Key replacement is a create, update, and revoke workflow.

## Create a key

1. Sign in to the console and select the workspace that should own the traffic.
2. Open **API keys** and create a named key using an owner or admin account.
3. Choose when it expires: in 30 days, 90 days (the default), 1 year, or never.
4. Copy the complete secret from the creation response and store it in your application's secret configuration.

The current key management service requires owner or admin access for key listing and changes. Workspace selection must match the authenticated management session.

Choose a name that identifies the application or environment. Names are trimmed, limited to 80 characters, and cannot contain control characters.

## One-time secret display

The full password is returned only when the key is created. Later key listings contain metadata and a suffix, not the secret. Treat the suffix as an identifier for troubleshooting, never as a usable password.

If you lose the secret or the creation response, create a replacement and revoke the inaccessible key. The existing secret cannot be recovered from the console's key metadata.

## Use and rename a key

The key secret is the password in [HTTP proxy Basic authentication or SOCKS5 username/password authentication](https://ports.io/docs/reference/authentication.md). Routing strategy and targeting belong in the username and can be changed without issuing another key.

Renaming changes the display name only. It does not replace the secret, alter its expiration, or rotate an exit. A revoked key cannot be renamed. Use separate keys when applications need independent access removal.

## Replace a key

For routine replacement:

1. Create a new key with the desired name and expiration.
2. Store it in your application's secret configuration.
3. Validate that the application can authenticate using the new key.
4. Update all application instances and scheduled jobs that use the old secret.
5. Revoke the old key after the transition is complete.

If a key has leaked, revoke it promptly and deploy a replacement. Revocation blocks new connections after its policy update reaches the proxy servers. It does not automatically close existing tunnels; see the propagation and tunnel behavior below.

Replacement does not require changing the routing username. Session bindings are scoped to the workspace rather than a particular key; using another key in the same workspace does not independently create a new session binding.

## Revoke or expire a key

Revocation is permanent. It preserves the key's ID, creator, timestamps, and associated usage history. Revoked keys cannot be re-enabled, and their history remains visible in the key list.

Each proxy server reloads revoked keys and disabled-workspace policy every 30 seconds. These changes normally reach new connections within about 30 seconds; a failed reload can delay propagation. Revocation is not an instantaneous distributed operation.

An expired key is rejected during new connection setup. Already established HTTP CONNECT and SOCKS5 tunnels do not recheck key validity and are not automatically closed by expiration, revocation, or a disabled workspace. They continue until a client or origin disconnects, a network failure occurs, or the 10-minute inactivity or 2-hour lifetime limit is reached. Close existing application connections you control when they must stop immediately.

A key with no expiration still remains subject to revocation and workspace authorization policy for new connections. These rules apply to both HTTP and SOCKS5 authentication.

## Key issuance capacity

The current service limits each workspace to 1,024 total issued keys, including retained expired and revoked keys. Revoking a key does not restore an issuance slot. Prefer stable application keys with deliberate replacement intervals over creating a key per request or per session.

If the console says the workspace has reached its key issuance limit, contact support about more capacity. If it says key issuance is temporarily at capacity, try again later. In both cases existing keys keep working and can still be revoked.

## Management authentication

Proxy secrets grant `proxy:connect`. Key-management requests use an authenticated console session, workspace authorization, and origin checks. The proxy password is not a bearer token for key-management endpoints. See [Authentication](https://ports.io/docs/reference/authentication.md) for the proxy connection credential format.