---
title: "Create a customer portal session"
method: POST
path: "/v1/customers/{customer_id}/portal-sessions"
tags: ["Customer sessions"]
---

# Create a customer portal session

`POST /v1/customers/{customer_id}/portal-sessions`

## Request

- Base URL: `https://api.bachs.io`
- URL: `https://api.bachs.io/v1/customers/{customer_id}/portal-sessions`
- Auth: HTTP bearer

Creates a pre-authenticated customer portal session and returns the URL that opens it. The URL carries the session credential, so redirect the customer to it and do not log or share it. Sessions are short-lived; create a fresh one each time a customer asks to manage their billing. Requires the `customers:write` scope.

## Path parameters

- `customer_id` string, required

## Response `200`

Success

- PortalSessionResponse
  - `id` string, required: The session identifier, prefixed with `psn_`. Use it to correlate a session with your own logs; it is not a credential and cannot be exchanged for access.
  - `url` string, uri, required: The URL that opens the portal as this customer. It carries the session credential, so it works on any device and must not be logged or shared.

## Other responses

- `401`: Unauthorized - Invalid, missing, or expired API key. Verify your API key is correctly formatted and included in the Authorization header as `Bearer sk_sandbox_...` or `Bearer sk_live_...`. Check that your key hasn't been revoked.
- `403`: Forbidden - API key does not have permission for the requested resource. Verify you're using the correct organization's API key and that you're not trying to access another organization's data.
- `404`: Not Found - The requested resource does not exist. Verify the resource ID is correct and that it belongs to your organization.
- `429`: Too Many Requests - Rate limit exceeded. Standard tier allows 100 requests per minute per API key. Wait a few seconds before retrying. Check X-RateLimit-Reset header for when the window resets.
- `500`: Internal Server Error - An unexpected error occurred while processing the request. Retry with exponential backoff. If the issue persists, contact support with your request context.
- `503`: Service Unavailable - The portal cannot issue sessions right now. Retry once; if it persists, contact support.

---

[API](https://skmtc.dev/bachs/apis/bachs-api.md) - [All operations](https://skmtc.dev/bachs/apis/bachs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bachs/apis/bachs-api/revisions/f29efa8a22df?raw)