Skip to content

chore: update API key docs for new orgs-scoped service keys #584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Brian Vander Schaaf (bvs-langchain) merged 4 commits into from
Sep 19, 2025
Merged

chore: update API key docs for new orgs-scoped service keys #584

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c05f6ad
chore: fix API key docs
bvs-langchain Sep 18, 2025
4077150
more detail
bvs-langchain Sep 18, 2025
330c9f0
Update src/langsmith/manage-organization-by-api.mdx
bvs-langchain Sep 19, 2025
2400cca
Update src/langsmith/administration-overview.mdx
bvs-langchain Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/langsmith/administration-overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ PATs are prefixed with `lsv2_pt_`

#### Service keys

Service keys are similar to PATs, but are used to authenticate requests to the LangSmith API on behalf of a service account. Only admins can create service keys. We recommend using these for applications / services that need to interact with the LangSmith API, such as LangGraph agents or other integrations. Service keys are scoped to a workspace and can be used to authenticate requests to the LangSmith API for that workspace.
Service keys are similar to PATs, but are used to authenticate requests to the LangSmith API on behalf of a service account. Only admins can create service keys. We recommend using these for applications / services that need to interact with the LangSmith API, such as LangGraph agents or other integrations. Service keys may be scoped to a single workspace, multiple workspaces, or the entire organization, and can be used to authenticate requests to the LangSmith API for whichever workspace(s) it can has access to.
Comment thread
bvs-langchain marked this conversation as resolved.
Outdated

Service keys are prefixed with `lsv2_sk_`

Expand Down
10 changes: 7 additions & 3 deletions src/langsmith/create-account-api-key.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebarTitle: Create an account and API key

To get started with LangSmith, you need to create an account. You can sign up for a free account [here](https://smith.langchain.com). We support logging in with Google, GitHub, and email.

![](/langsmith/images/create-account.png)
![Create account](/langsmith/images/create-account.png)

## API keys

Expand All @@ -25,16 +25,20 @@ To create either type of API key head to the [Settings page](https://smith.langc
The API key will be shown only once, so make sure to copy it and store it in a safe place.
</Note>

![](/langsmith/images/create-api-key.png)
![Create API key](/langsmith/images/create-api-key.png)

## Configure the SDK

You may set the following environment variables in addition to `LANGSMITH_API_KEY`.

This is only required if using the EU instance.

`LANGSMITH_ENDPOINT=``https://api.smith.langchain.com`
`LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com`
Comment thread
bvs-langchain marked this conversation as resolved.

This is only required for keys scoped to more than one workspace.

`LANGSMITH_WORKSPACE_ID=<Workspace ID>`

## Using API keys outside of the SDK

See [instructions for managing your organization via API](/langsmith/manage-organization-by-api).
9 changes: 5 additions & 4 deletions src/langsmith/manage-organization-by-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Before diving into this content, it might be helpful to read the following:
There are a few limitations that will be lifted soon:

* The LangSmith SDKs do not support these organization management actions yet.
* [Service Keys](/langsmith/administration-overview#api-keys) don't have access to newly-added workspaces yet (we're adding support soon). We recommend using a PAT of an Organization Admin for now, which by default has the required permissions for these actions.
* Organization-scoped [service keys](/langsmith/administration-overview#service-keys) with Organization Admin permission may be used for these actions.
</Note>

Some commonly-used endpoints and use cases are listed below. For a complete list of available endpoints, see the [API docs](https://api.smith.langchain.com/redoc). **The `X-Organization-Id` header should be present on all requests, and `X-Tenant-Id` header should be present on requests that are scoped to a particular workspace.**
Expand All @@ -42,8 +42,9 @@ Some commonly-used endpoints and use cases are listed below. For a complete list

Organization level:

* [List organization members](https://api.smith.langchain.com/redoc#tag/orgs/operation/get_current_org_members_api_v1_orgs_current_members_get)
* [Invite a user to the organization and one or more workspaces](https://api.smith.langchain.com/redoc#tag/workspaces/operation/add_member_to_current_workspace_api_v1_workspaces_current_members_post) . This should be used when the user is not already a member in the organization.
* [List active organization members](https://api.smith.langchain.com/redoc#tag/orgs/operation/get_current_active_org_members_api_v1_orgs_current_members_active_get)
* [List pending organization members](https://api.smith.langchain.com/redoc#tag/orgs/operation/get_current_pending_org_members_api_v1_orgs_current_members_pending_get)
* [Invite a user to the organization and one or more workspaces](https://api.smith.langchain.com/redoc#tag/orgs/operation/add_members_to_current_org_batch_api_v1_orgs_current_members_batch_post) . This should be used when the user is not already a member in the organization.
Comment thread
bvs-langchain marked this conversation as resolved.
Outdated
* [Update a user's organization role](https://api.smith.langchain.com/redoc#tag/workspaces/operation/add_member_to_current_workspace_api_v1_workspaces_current_members_post)
* [Remove someone from the organization](https://api.smith.langchain.com/redoc#tag/orgs/operation/remove_member_from_current_org_api_v1_orgs_current_members__identity_id__delete)

Expand All @@ -61,7 +62,7 @@ These params should be omitted: `read_only` (deprecated), `password` and `full_n
## API keys

<Note>
Use the `X-Tenant-Id` header to specify which workspace to target. If the header is not present, operations will default to the workspace the API key was initially created in.
Use the `X-Tenant-Id` header to specify which workspace to target. If the header is not present, operations will default to the workspace the API key was initially created in. **If `X-Tenant-Id` is not specified when accessing workspace-scoped resources with an organization-scoped API key, the request will fail with `403 Forbidden`.**
</Note>

* [Create a service key](https://api.smith.langchain.com/redoc#tag/api-key/operation/generate_api_key_api_v1_api_key_post)
Expand Down