> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.instabase.com/admin/service-accounts/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server. # Managing service accounts > Manage service accounts and their API tokens. AI Hub supports creating service accounts, which are AI Hub accounts not tied to a particular member and used only for interacting with the AI Hub [API and SDK](/api-sdk/using-api-sdk). Service accounts can be added to groups and workspaces and assigned roles just like a standard member account. Service accounts are commonly used for programmatic interactions, such as triggering runs as part of a continuous development pipeline or performing automated tasks on a set schedule. Service accounts can use AI Hub-managed API tokens or, for Enterprise-tier organizations with [external OAuth](/admin/security/oauth-providers) enabled, externally managed tokens from your OAuth provider. Users with admin permissions can create and manage service accounts. ## Adding service accounts Any number of service accounts can be created. 1. In the header, click the initials icon and select **Settings**. Select the organization name tab. 2. On the **Service accounts** tab, click **Add service account**. 3. Add a display name for the service account, reflecting the account's intended usage. 4. Select an [organization role](/admin/roles/). 5. Click **Create**. 6. Add the account's first AI Hub-managed API token or click **Skip**. #### Creating API tokens 1. Enter a name and description for the token. Use the description to note the token's purpose or intended usage. 2. Select or define a custom expiration date for the token. The default setting is *Never expires*. 3. Click **Add**. 4. Copy the token. After closing the create token dialog, the token's value is encrypted and can't be copied again. > **What's next** > > After creating a service account, ensure it can access the appropriate resources. Like any other organization member, service accounts must be granted access to organization resources. For example, if you want a service account to be able to run a given deployment, it must have access to the workspace where that deployment was created. Next steps might include: > > * Add the service account to [shared workspaces](/admin/workspace-members/) and [assign workspace roles](/admin/roles#assigning-roles). Only the service account's organization role is managed from the service accounts tab. > > * Add the service account to [groups](/admin/group-management#managing-group-members), if using groups to manage workspace access. > > * Ensure any apps you want the service account to run are shared with the organization. > > * If using externally managed tokens, [create an OAuth account mapping](/admin/security/oauth-mappings). ### Using service accounts When using service accounts, consider the following information and guidelines. * **Service accounts are organization members** -- Service accounts belong to the organization, not to the member who created them. Service accounts don't inherit your role, your access, or any other properties. You must grant the service account its own permissions and access to resources. * **Service accounts support multiple authentication methods** -- Service accounts can use AI Hub-managed API tokens (created from the service account details page) or externally managed tokens from your OAuth provider (configured through account mappings). All AI Hub-managed tokens for a service account share the same role-based access. Externally managed tokens can either use the mapped account's roles or, when configured with a valid scope claim, a subset of roles defined in the token. * **Service accounts don't have a personal workspace** -- A personal workspace isn't created for each service account. Because service accounts don't have a personal workspace, requests that default to saving output to a personal workspace fail. For example, when using the [run app](/api-sdk/api-reference/runs/run-app/) endpoint, always define an output workspace or directory to which the service account has access. * **Service accounts have their own user ID** -- If you need to search for or specify a service account's user ID, you can find it on the service account details page. Navigate to **Settings** > organization name > **Service accounts**, then select the service account. * **Service accounts use organization context by default** -- Service account API requests default to the organization context when the [`IB-Context` header](/api-sdk/authorization#ib-context-header) is undefined. You can omit the header for service account requests. ## Managing API tokens From a service account's details page, you can manage its AI Hub-managed API tokens. ### Adding API tokens One service account can have multiple API tokens. Consider using one token per API or SDK workflow for fine-grained controls. All AI Hub-managed API tokens created for a service account share the same role-based access. 1. In the header, click the initials icon and select **Settings**. Select the organization name tab. 2. On the **Service accounts** tab, select the service account. 3. In the **AI Hub tokens** section, click **Create token**. 4. Enter a name and description for the token. Use the description to note the token's purpose or intended usage. 5. Select or define a custom expiration date for the token. The default setting is *Never expires*. 6. Click **Add**. 7. Copy the token. After closing the create token dialog, the token's value is encrypted and can't be copied again. ### Refreshing tokens You can refresh a token as needed. Refreshing a token updates its value. 1. In the header, click the initials icon and select **Settings**. Select the organization name tab. 2. On the **Service accounts** tab, select the service account. 3. In the AI Hub tokens table, click the refresh icon ![Icon of two circling arrows.](/_fern-img/c92b6852a1e77d2aea705ec90d8d76957c2fff38478a2b3b80c04985110df5fc.webp) of the token to refresh. 4. Select or define a custom expiration date for the token. The default setting is *Never expires*. 5. Click **Refresh token**. 6. Copy the token. After closing the refresh token dialog, the token's value is encrypted and can't be copied again. ### Deleting tokens If a token is no longer needed or you wish to revoke the access it grants, you can delete it. 1. In the header, click the initials icon and select **Settings**. Select the organization name tab. 2. On the **Service accounts** tab, select the service account. 3. In the AI Hub tokens table, click the delete icon ![Icon of a trash can.](/_fern-img/fde5c4ebfaee103ef10fc55c5b5119885924befbf5e79ea1da8cbf46d20448a8.webp) of the token to delete. 4. Enter the confirmation text and click **Delete token**. > **Tip** > > To delete all tokens, click **More** above the API tokens table, then select **Delete all tokens**. ### Managing OAuth account mappings Enterprise For Enterprise-tier organizations with [external OAuth provider configuration](/admin/security/oauth-providers) enabled, service accounts can use tokens issued by your OAuth provider instead of AI Hub-managed tokens. To enable this functionality, you must [create an account mapping](/admin/security/oauth-mappings) that links the service account to an external identity in your OAuth provider. ## Disabling service accounts Disabling a service account lets you revoke the account's access and permissions without also removing the account from any groups or workspaces to which it was added. When disabling a service account, all AI Hub-managed API tokens associated with the account are permanently deleted. OAuth account mappings are preserved but can't be used while the account is disabled. You can re-enable service accounts later, though previously created API tokens aren't restored. 1. In the header, click the initials icon and select **Settings**. Select the organization name tab. 2. On the **Service accounts** tab, click the overflow icon ![Icon with three stacked vertical dots.](/_fern-img/a83e2b40897c8c3871ed84b69fd99d990dbe0eb9bc3936ad84addb6d2ce31f95.webp) of the account to disable, then select **Disable**. 3. Click **Disable** to confirm. > **Tip** > > You can enable previously disabled service accounts. In the service accounts list, click the overflow icon of the service account, then select **Enable**. ## Deleting service accounts Deleting a service account permanently deletes the account, all associated AI Hub-managed API tokens, and all OAuth account mappings. 1. In the header, click the initials icon and select **Settings**. Select the organization name tab. 2. On the **Service accounts** tab, click the overflow icon ![Icon with three stacked vertical dots.](/_fern-img/a83e2b40897c8c3871ed84b69fd99d990dbe0eb9bc3936ad84addb6d2ce31f95.webp) of the account to delete, then select **Delete service account**. 3. Click **Remove** to confirm. > Manage service accounts and their API tokens.