> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/en/troubleshooting/permission-and-auth-errors.md).

# Permission and Authentication Errors

This is to identify when the operation should be possible but is refused, the API/SDK returns 401/403, the external service connection cannot be used, or the page requires re-authentication after opening. The target audience is users and administrators. Even though the symptoms are similar, the user's role, Project API key, external connection, and Page session are different causes. Isolate which path failed before replacing credentials or expanding privileges.

## Related articles

* [Understand organization/Project/App permissions](/en/administration-and-operations/understand-org-project-app-permissions.md)
* [Respond to connection expiry/change of person in charge](/en/administration-and-operations/handle-expired-connections-and-owner-changes.md)
* [Manage Project API keys](/en/administration-and-operations/manage-project-api-keys.md)

## Scope of this article

This article is a guide to distinguish between rejections or authentication failures regarding roles, API keys, external connections, and Page sessions. Issuance, switching, and revocation of keys are handled in [Manage Project API keys](/en/administration-and-operations/manage-project-api-keys.md), repair and transfer of external connections are handled in [Respond to connection expiration and change of person in charge](/en/administration-and-operations/handle-expired-connections-and-owner-changes.md), and page access mode settings are handled in [Register and publish Pages from the screen](/en/build-pages-skills-and-resource-linking/register-and-publish-pages.md). This article alone does not conclude that failures in building or displaying the Page itself, communication failures, or errors in input content are due to authentication/authorization problems.

## Check first

* [ ] We have identified the failed target (screen operation, external linkage, Page, API/SDK) and the organization/Project/App name.
* [ ] The user who performed the operation, the user account, the API key usage name, or the connection name were recorded separately.
* [ ] The HTTP status, displayed message, date and time of occurrence, and steps to reproduce were recorded.
* [ ] The actual values ​​of API keys, passwords, tokens, cookies, and Secrets are not included in logs, screen sharing, and inquiries.
* [ ] Before deleting, reissuing, or re-authenticating connections/keys, we checked the affected automatic processes and users.

> To resolve the error, do not accept other people's authentication information, put the key in browser-side code, create a full-scope key, or share it with everyone. Confirm by narrowing down the necessary targets, operations, and responsibilities.

## Sort by symptom

| Symptoms/Displayed Messages                                                                                                                                                                                                                                                            | Main Causes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Checks/Treatments                                                                                                                                                                                                                                                                                                             | Detailed Articles                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "You do not have permission to perform this operation" "Access is denied" "You do not have permission to use this agent. Please contact your administrator."                                                                                                                           | Organization role, Project role, IAM, or individual resource sharing/policy is missing                                                                                                                                                                                                                                                                                                                                                                                                                   | Separate the target organization/project/resource from the failed operation such as viewing/executing/editing. The administrator checks the basic role, project participation, and IAM and sharing scope if necessary. Users make requests without changing their roles at their own discretion.                              | [Understand permissions for organizations, projects, and apps](/en/administration-and-operations/understand-org-project-app-permissions.md)                                                                                                                          |
| The screen opens, but you cannot edit, delete, or change settings.                                                                                                                                                                                                                     | You have permission to view and execute, but you do not have the role or IAM permissions to perform modification operations.                                                                                                                                                                                                                                                                                                                                                                             | Record which button or target failed. Don't assume that you can make changes based solely on participating in a project or being an organization administrator. Request the minimum necessary operations to the administrator.                                                                                                | [Understand permissions for organizations, projects, and apps](/en/administration-and-operations/understand-org-project-app-permissions.md)                                                                                                                          |
| API/SDK returns 401 (Unauthorized) or "Authentication is required"                                                                                                                                                                                                                     | Authentication information may be unspecified, malformed, invalid, or the required authentication method may not be passed in the request path                                                                                                                                                                                                                                                                                                                                                           | Check the execution destination, authentication method, and target Project. Re-paste the key value and check the approved storage and setting destinations without sharing. Before reissuing, check the expiration, expiration date, and usage of the existing key.                                                           | [Manage Project API keys](/en/administration-and-operations/manage-project-api-keys.md)                                                                                                                                                                              |
| API/SDK returns 403 (Forbidden)                                                                                                                                                                                                                                                        | Even if you have been authenticated, you may not have the necessary scope or execution privileges, or the status of the key, organization, or creator may not meet the usage conditions                                                                                                                                                                                                                                                                                                                  | Check the requested target/operation with the scope set for the key. Only if the required range is insufficient, a new key with the minimum scope and new deadline will be issued, and the old key will be invalidated after switching.                                                                                       | [Manage Project API keys](/en/administration-and-operations/manage-project-api-keys.md)                                                                                                                                                                              |
| API/SDK returns a response indicating an invalid/expired key, or fails after revocation                                                                                                                                                                                                | Key value mix-up, deletion/expiration, or creator loses access to the project, etc.                                                                                                                                                                                                                                                                                                                                                                                                                      | Record the response body and check the target project, key name, expiration date, whether it has been deleted or revoked, the creator, and the system used. Since you can only see the actual value at the time of creation, issue a new key and switch safely without trying to restore the lost actual value from the list. | [Manage Project API keys](/en/administration-and-operations/manage-project-api-keys.md)                                                                                                                                                                              |
| "Re-authentication required" "Linkage has been disabled. Please re-authenticate with the same account." or "Authentication failed. If the problem persists, please contact the administrator." Connectors added or changed during app installation/update may not have been configured | Check whether it is a personal connection or a shared connection, the connection destination, connection name, and authenticated account. For personal connections, the person himself/herself re-authenticates using the same account. Users do not replace shared connections with other personal connections; administrators review the scope of impact and take action. Immediately after installing or updating the app, check the connector requirements and the person in charge of setting them. | [Respond to connection expiration and change of person in charge](/en/administration-and-operations/handle-expired-connections-and-owner-changes.md)                                                                                                                                                                          |                                                                                                                                                                                                                                                                      |
| Authentication is required while operating a Page; it may or may not be available after reloading                                                                                                                                                                                      | Sign-in or Page session may have expired or become invalid depending on the Page's access mode                                                                                                                                                                                                                                                                                                                                                                                                           | First, check the Page URL, access mode, user account, and previous operation. Reload the page or perform the authentication as instructed, and if the same symptoms persist, do not repeat the issue and contact the Page administrator. Use the authentication route provided on the external customer authentication page.  | [Register and publish Pages from the screen](/en/build-pages-skills-and-resource-linking/register-and-publish-pages.md), [Understand permissions for organizations, projects, and apps](/en/administration-and-operations/understand-org-project-app-permissions.md) |

## Distinguish between 401 and 403

HTTP status is the entry point for identification. Since the cause cannot be uniquely determined for every API/screen, check the response body, execution path, and target operation as well.

| Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basic meaning                                                                                                        | Things to check first                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 401 (Unauthorized)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Authentication information is missing, invalid, or authentication may not be possible through that route.            | Check the authentication method, setting destination, target Project, and validity of the authentication information. |
| 403 (Forbidden)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Possibility of not being allowed even after authentication or not meeting the usage conditions for a protected route | Check the required scope, role, project participation, key expiration date, creator, and organizational status.       |
| In some implementations that use Project API keys, 403 results may occur due to unspecified keys, invalid keys, expired keys, or lack of required scopes. Conversely, depending on the public API operation, invalid or unspecified API keys will be reported as 401, and missing required scopes will be reported as 403. \*\*Do not automatically decide that if it is 401, recreate the key, or if it is 403, maximize privileges. \*\* Check the specifications of the request destination and the message returned. |                                                                                                                      |                                                                                                                       |

## Steps to isolate the cause

1. Check the person's role. \*\* If only certain editing/management operations fail in the browser, check the organization role, project role, IAM, and sharing scope. Participation in a project and operation privileges for individual resources are different.
2. \*\*Check if it is an API key. \*\* If the API/SDK fails, check the target project, key usage name, expiration date, deletion/revocation, required scope, and setting destination. We do not assume that the key value or scope will be edited later, and if changes are necessary, we will safely issue a new key, switch it, or revoke the old key.
3. \*\*Check if it is an external connection. \*\* For "re-authentication required", "unlinked", etc., check the connection owner and the account/authority of the external service. During a change of responsibility, the successor prepares his or her own connections rather than inheriting the personal connections of the predecessor.
4. Check if it is a \*\*Page session. \*\* If it occurs only while viewing or operating a page, check the account or external authentication that matches the access mode, and record the status after reloading and reauthenticating. There is no workaround by changing the Page to public settings.
5. \*\*Check the reproduction range. \*\* Distinguish between only the same users, all members of the same project, or only the same external service, API key, or page. Avoid duplicate reruns and multiple key issuances.

## Common Misconceptions

* **Joining a Project does not necessarily mean that you can perform all operations**. Separately check roles, IAM, individual resource sharing/policies, and permissions on the external service side.
* **Not all APIs can be called with an API key**. The target project, scope, expiration date, and organization terms and conditions are relevant.
* **If it is "connected", it does not necessarily mean that the external process will be successful**. Also check the data permissions, authentication account, and connection status on the external service side.
* **It does not necessarily mean that you should increase your privileges once you are re-authenticated by Page.** Identifies whether the problem is the access mode and Page session, or the permissions of the function to be executed.

## Before consulting with administrator/support

Record the following: For details on how to collect information, please refer to [Collect information required for inquiries](/en/troubleshooting/collect-info-for-support.md).

* Organization, Project, App/Page/API target name, user or key usage name (excluding actual value)
* Failed operation/request destination, HTTP status, display message, date and time of occurrence, steps to reproduce
* User role confirmation results, required operations, individual/shared connection, and whether re-authentication is performed
* API key: expiration date, scope, deletion/revocation, switching status; page: URL, access mode, status after re-authentication

## Read next article

* [Understand organization/Project/App permissions](/en/administration-and-operations/understand-org-project-app-permissions.md)
* [Respond to connection expiry/change of person in charge](/en/administration-and-operations/handle-expired-connections-and-owner-changes.md)
* [Manage Project API keys](/en/administration-and-operations/manage-project-api-keys.md)
* [Not displayed/Cannot participate](/en/troubleshooting/not-visible-cannot-join.md)
