> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth Access Tokens 컬렉션

`oauthAccessTokens`에는 web이 받아들이는 bearer 토큰이 저장됩니다. Ayakaleaf Pro에서는 사용자가 계정 설정 페이지에서 만들어 git-bridge와 MCP 엔드포인트에 사용하는 개인 액세스 토큰(Git 인증 토큰)입니다. 문서 하나가 토큰 하나입니다. 스키마는 `services/web/app/src/models/OauthAccessToken.mjs`이며, web 모듈 `oauth2-server`가 주로 네이티브 드라이버로 컬렉션에 씁니다.

#### 필드

| 필드 | 타입 | 의미 | 출처 |
| - | - | - | - |
| `_id` | ObjectId | 토큰 문서 id. 설정 페이지는 이 id로 토큰을 삭제합니다. | `OauthAccessToken.mjs:6` |
| `accessToken` | String | 토큰의 SHA-256 16진수 다이제스트. 평문 토큰(`olp_`와 무작위 영문자·숫자 36자)은 생성 시 한 번만 표시되며 저장되지 않습니다. | `OauthAccessToken.mjs:8`, `services/web/modules/oauth2-server/app/src/OAuthPersonalAccessTokenManager.mjs:54,72`, `services/web/modules/oauth2-server/app/src/SecretsHelper.mjs:6-11` |
| `accessTokenPartial` | String | 평문 토큰의 처음 8자로, 토큰 목록에 표시됩니다. | `OauthAccessToken.mjs:9`, `OAuthPersonalAccessTokenManager.mjs:73` |
| `type` | String | 설정 페이지에서 만든 모든 토큰은 `personal_access_token`입니다. 목록, 개수, 삭제 쿼리가 이 값으로 필터링합니다. | `OauthAccessToken.mjs:10`, `OAuthPersonalAccessTokenManager.mjs:75` |
| `accessTokenExpiresAt` | Date | 생성 후 1년. 이후 두 토큰 검사 모두 토큰을 거부하고, TTL 인덱스가 하루 뒤 삭제합니다. | `OauthAccessToken.mjs:11`, `OAuthPersonalAccessTokenManager.mjs:65-68,77` |
| `oauthApplication_id` | ObjectId | [OAuth Applications](https://ayakaleaf-pro.mintlify.site/ko/dev/data-model/oauth-applications-collection.md)에 있는 `Overleaf Git Bridge` 클라이언트의 `_id`. | `OauthAccessToken.mjs:12`, `OAuthPersonalAccessTokenManager.mjs:55-56,74` |
| `scope` | String | 공백으로 구분된 스코프. 개인 액세스 토큰은 git-bridge와 MCP 라우트가 요구하는 스코프인 `git_bridge`를 받습니다. | `OauthAccessToken.mjs:15`, `OAuthPersonalAccessTokenManager.mjs:76` |
| `user_id` | String (ObjectId in the schema) | 토큰 소유자. `createToken`은 세션의 사용자 id를 네이티브 드라이버로 그대로 문자열로 저장하며, 관리자 패널도 문자열로 조회합니다(`services/web/modules/admin-tools/app/src/AdminUserListManager.mjs:391-392`). | `OauthAccessToken.mjs:16`, `services/web/modules/oauth2-server/app/src/OAuthPersonalAccessTokenController.mjs:29-41`, `OAuthPersonalAccessTokenManager.mjs:78,83-85` |
| `createdAt` | Date | 생성 시각. 토큰 목록은 이 값으로 최신순 정렬됩니다. | `OauthAccessToken.mjs:17`, `OAuthPersonalAccessTokenManager.mjs:21-22,64,79` |
| `lastUsedAt` | Date | 토큰이 마지막으로 검사를 통과한 시각. 두 토큰 검사 모두 이 값을 설정합니다. | `OauthAccessToken.mjs:19`, `services/web/modules/oauth2-server/app/src/OAuth2Model.mjs:58-61`, `OAuthPersonalAccessTokenManager.mjs:136-140` |
| `refreshToken`, `refreshTokenExpiresAt` | String, Date | `saveToken`만 이 값을 쓰며(리프레시 토큰은 해시), `saveToken`을 호출하는 곳은 없습니다. [OAuth Applications](https://ayakaleaf-pro.mintlify.site/ko/dev/data-model/oauth-applications-collection.md)를 참조하세요. | `OauthAccessToken.mjs:13-14`, `OAuth2Model.mjs:249-252` |
| `expiresAt` | Date | 스키마에만 있습니다. 이 저장소의 어떤 코드도 쓰지 않습니다. TTL 인덱스가 적용됩니다. | `OauthAccessToken.mjs:18` |
| `lastNotifiedAt.warning`, `lastNotifiedAt.expired`, `notificationsSuppressedAt` | Date | 스키마에만 있습니다. 이 저장소의 어떤 코드도 읽거나 쓰지 않습니다. | `OauthAccessToken.mjs:20-27` |

#### 쓰는 코드

| 코드 | 역할 |
| - | - |
| `OAuthPersonalAccessTokenManager.mjs:53-88` (`createToken`) | 개인 액세스 토큰을 삽입합니다. 라우트 `POST /oauth/personal-access-tokens`(`services/web/modules/oauth2-server/app/src/OAuthPersonalAccessTokenRouter.mjs:22-27`)는 사용자의 `gitBridge` 기능이 필요하며 사용자당 토큰 10개를 허용합니다(`OAuthPersonalAccessTokenController.mjs:7,34-38`). |
| `OAuthPersonalAccessTokenManager.mjs:90-105` (`removeToken`) | 사용자의 토큰 하나를 삭제합니다. 라우트 `DELETE /oauth/personal-access-tokens/:token_id`(`OAuthPersonalAccessTokenRouter.mjs:29-32`). |
| `OAuthPersonalAccessTokenManager.mjs:136-140`, `OAuth2Model.mjs:58-61` | 검사에 성공하면 `lastUsedAt`을 설정합니다. |

#### 읽는 코드

| 코드 | 역할 |
| - | - |
| `OAuthPersonalAccessTokenManager.mjs:107-144` (`verifyToken`) | `GET /oauth/token/info`(`OAuthPersonalAccessTokenRouter.mjs:11-15`)를 위해 해시로 토큰을 검사합니다. git-bridge는 git clone과 push 때 이를 호출합니다(`services/git-bridge/src/main/java/uk/ac/ic/wlgitbridge/server/Oauth2Filter.java:285`). 만료된 토큰과 정지되었거나 삭제된 사용자의 토큰을 거부합니다. |
| `OAuth2Model.mjs:31-82` (`getAccessToken`) | `AuthenticationController.requireOauth('git_bridge')`(`services/web/app/src/Features/Authentication/AuthenticationController.mjs:409-450`)를 위해 bearer 토큰을 검사합니다. 대상은 git-bridge API 라우트(`services/web/modules/git-bridge/app/src/GitBridgeRouter.mjs:33-59`)와 MCP 엔드포인트(`services/web/modules/mcp-server/app/src/McpRouter.mjs:16-22`)입니다. 만료된 토큰과 정지되었거나 삭제된 사용자의 토큰을 거부합니다. |
| `OAuthPersonalAccessTokenManager.mjs:13-50` (`listTokens`, `getUserTokenNums`) | 설정 페이지에 사용자의 토큰을 나열하고(`GET /oauth/personal-access-tokens`) 한도 확인을 위해 개수를 셉니다. |
| `AdminUserListManager.mjs:388-400` (module `admin-tools`) | 관리자 패널에 사용자의 토큰 접두사를 표시합니다. |

#### 인덱스

| 이름 | 키 | 옵션 | 마이그레이션 |
| - | - | - | - |
| `refreshToken_1` | `{ refreshToken: 1 }` | 고유, 부분 인덱스: `refreshToken` 존재 | `20230405190240_oauth_refresh_tokens_index.mjs` |
| `expiresAt_1` | `{ expiresAt: 1 }` | TTL, `expireAfterSeconds: 0`, 부분 인덱스: `expiresAt` 존재 | `20230406125632_oauth_tokens_ttl.mjs` |
| `user_id_1_type_1` | `{ user_id: 1, type: 1 }` | | `20250321160345_add_type_to_pat_user_id_index.mjs`(`20250115110745_oauth_user_id_index_no_partial.mjs`의 `user_id_1`을 대체하며, 그것은 `20230426095212_personal_oauth_tokens_user_index.mjs`의 `pat_user_id_1`을 대체했음) |
| `accessTokenExpiresAt_1` | `{ accessTokenExpiresAt: 1 }` | TTL, `expireAfterSeconds: 86400`, 부분 인덱스: `accessTokenExpiresAt` 존재 | `20260511104500_expire_oauthAccessTokens.mjs` |

마이그레이션은 `tools/migrations/`에 있습니다. 고유 인덱스 `accessToken_1`은 `saas`와 `server-pro` 태그가 붙은 마이그레이션에서만 만들어지므로, Community Edition에는 `accessToken`에 인덱스가 없습니다.

#### 참고

* 사용자를 삭제해도 그 토큰은 삭제되지 않습니다. `UserDeleter`가 `cleanupPersonalAccessTokens` 훅을 실행하지만(`services/web/app/src/Features/User/UserDeleter.mjs:230-234`), 이를 수신하는 모듈은 없습니다. 사용자가 없으므로 두 토큰 검사 모두 토큰을 거부하고, TTL 인덱스가 `accessTokenExpiresAt` 하루 뒤에 제거합니다.
* 사용자를 정지하면 세션만 종료됩니다. 토큰은 남아 있으며, `users.suspended`가 `true`인 동안 두 토큰 검사 모두 이를 거부합니다(`OAuth2Model.mjs:51-54`, `OAuthPersonalAccessTokenManager.mjs:129-134`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.