identity

인증·me·PAT·OAuth/OIDC·well-known

10 operations — 인증·me·PAT·OAuth/OIDC·well-known

`GET /.well-known/jwks.json`

authGetWellKnownJwksJson

AX Hub 발급 JWT 의 서명 검증용 public JWK 목록.

호출 권한: public. 인증 불필요 (verify endpoint).
응답에는 active + grace window (31일) 의 public 키만 포함. 회전 후 31일은 구 키로 서명된 JWT 도 검증됨.
Cache-Control: public, max-age=3600 헤더 set — 클라이언트가 1시간 캐시.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.identity(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthGetWellKnownJwksJson(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authGetWellKnownJwksJson(pathParams, query, body)` — 비동기: `authGetWellKnownJwksJsonAsync(…)` → CompletableFuture
kotlin	`client.identity.authGetWellKnownJwksJson(pathParams, query, body)` — suspend
python	`client.identity.auth_get_well_known_jwks_json(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_get_well_known_jwks_json(path_params: …, query: …, body: …)`
공통	`request("authGetWellKnownJwksJson", pathParams, query, body)`

응답 — 200 · JWK Set

이름	타입	설명
`keys`	array<object>	Keys 는 verify 에 사용 가능한 public JWK 목록 (active + grace window 의 키).

에러 status: 500 — 에러 처리

`GET /.well-known/oauth-authorization-server`

authGetWellKnownOauthAuthorizationServer

OpenID Connect Discovery 1.0 의 표준 metadata. Authorization Server endpoint URL + 지원 기능 광고.

호출 권한: public. 인증 불필요.
응답은 부팅 시 issuer URL 로 생성된 static doc — 매 호출 동일.
클라이언트 SDK 가 이 doc 로 /oauth/authorize, /oauth/token, /oauth/userinfo, /.well-known/jwks.json 위치를 자동 발견.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.identity(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthGetWellKnownOauthAuthorizationServer(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authGetWellKnownOauthAuthorizationServer(pathParams, query, body)` — 비동기: `authGetWellKnownOauthAuthorizationServerAsync(…)` → CompletableFuture
kotlin	`client.identity.authGetWellKnownOauthAuthorizationServer(pathParams, query, body)` — suspend
python	`client.identity.auth_get_well_known_oauth_authorization_server(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_get_well_known_oauth_authorization_server(path_params: …, query: …, body: …)`
공통	`request("authGetWellKnownOauthAuthorizationServer", pathParams, query, body)`

응답 — 200 · OIDC discovery

이름	타입	설명
`authorizationEndpoint` (wire: `authorization_endpoint`)	string	AuthorizationEndpoint 는 `/oauth/authorize`.
`codeChallengeMethodsSupported` (wire: `code_challenge_methods_supported`)	array<string>	CodeChallengeMethodsSupported 는 PKCE method (`S256`).
`grantTypesSupported` (wire: `grant_types_supported`)	array<string>	GrantTypesSupported 는 지원 grant_type.
`idTokenSigningAlgValuesSupported` (wire: `id_token_signing_alg_values_supported`)	array<string>	IDTokenSigningAlgValuesSupported 는 id_token 서명 algorithm (`RS256`).
`issuer`	string	Issuer 는 토큰의 iss claim. 본 hub 의 public URL.
`jwksUri` (wire: `jwks_uri`)	string	JWKSURI 는 `/.well-known/jwks.json`.
`registrationEndpoint` (wire: `registration_endpoint`)	string	RegistrationEndpoint advertises RFC 7591 Dynamic Client Registration when the MCP DCR launch gate is enabled. Omitted otherwise so clients do not attempt public writes against disabled deployments.
`resourceIndicatorsSupported` (wire: `resource_indicators_supported`)	boolean	ResourceIndicatorsSupported advertises RFC 8707 `resource` parameter support.
`responseTypesSupported` (wire: `response_types_supported`)	array<string>	ResponseTypesSupported 는 지원 response_type (`code` 만).
`revocationEndpoint` (wire: `revocation_endpoint`)	string	RevocationEndpoint 는 `/oauth/revoke`.
`scopesSupported` (wire: `scopes_supported`)	array<string>	ScopesSupported 는 지원 scope.
`subjectTypesSupported` (wire: `subject_types_supported`)	array<string>	SubjectTypesSupported 는 sub claim 형태 (`public`).
`tokenEndpoint` (wire: `token_endpoint`)	string	TokenEndpoint 는 `/oauth/token`.
`tokenEndpointAuthMethodsSupported` (wire: `token_endpoint_auth_methods_supported`)	array<string>	TokenEndpointAuthMethodsSupported 는 `/oauth/token` 의 client 인증 방식.
`userinfoEndpoint` (wire: `userinfo_endpoint`)	string	UserInfoEndpoint 는 `/oauth/userinfo`.

`GET /.well-known/openid-configuration`

authGetWellKnownOpenidConfiguration

OpenID Connect Discovery 1.0 의 표준 metadata. Authorization Server endpoint URL + 지원 기능 광고.

호출 권한: public. 인증 불필요.
응답은 부팅 시 issuer URL 로 생성된 static doc — 매 호출 동일.
클라이언트 SDK 가 이 doc 로 /oauth/authorize, /oauth/token, /oauth/userinfo, /.well-known/jwks.json 위치를 자동 발견.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.identity(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthGetWellKnownOpenidConfiguration(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authGetWellKnownOpenidConfiguration(pathParams, query, body)` — 비동기: `authGetWellKnownOpenidConfigurationAsync(…)` → CompletableFuture
kotlin	`client.identity.authGetWellKnownOpenidConfiguration(pathParams, query, body)` — suspend
python	`client.identity.auth_get_well_known_openid_configuration(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_get_well_known_openid_configuration(path_params: …, query: …, body: …)`
공통	`request("authGetWellKnownOpenidConfiguration", pathParams, query, body)`

응답 — 200 · OIDC discovery

이름	타입	설명
`authorizationEndpoint` (wire: `authorization_endpoint`)	string	AuthorizationEndpoint 는 `/oauth/authorize`.
`codeChallengeMethodsSupported` (wire: `code_challenge_methods_supported`)	array<string>	CodeChallengeMethodsSupported 는 PKCE method (`S256`).
`grantTypesSupported` (wire: `grant_types_supported`)	array<string>	GrantTypesSupported 는 지원 grant_type.
`idTokenSigningAlgValuesSupported` (wire: `id_token_signing_alg_values_supported`)	array<string>	IDTokenSigningAlgValuesSupported 는 id_token 서명 algorithm (`RS256`).
`issuer`	string	Issuer 는 토큰의 iss claim. 본 hub 의 public URL.
`jwksUri` (wire: `jwks_uri`)	string	JWKSURI 는 `/.well-known/jwks.json`.
`registrationEndpoint` (wire: `registration_endpoint`)	string	RegistrationEndpoint advertises RFC 7591 Dynamic Client Registration when the MCP DCR launch gate is enabled. Omitted otherwise so clients do not attempt public writes against disabled deployments.
`resourceIndicatorsSupported` (wire: `resource_indicators_supported`)	boolean	ResourceIndicatorsSupported advertises RFC 8707 `resource` parameter support.
`responseTypesSupported` (wire: `response_types_supported`)	array<string>	ResponseTypesSupported 는 지원 response_type (`code` 만).
`revocationEndpoint` (wire: `revocation_endpoint`)	string	RevocationEndpoint 는 `/oauth/revoke`.
`scopesSupported` (wire: `scopes_supported`)	array<string>	ScopesSupported 는 지원 scope.
`subjectTypesSupported` (wire: `subject_types_supported`)	array<string>	SubjectTypesSupported 는 sub claim 형태 (`public`).
`tokenEndpoint` (wire: `token_endpoint`)	string	TokenEndpoint 는 `/oauth/token`.
`tokenEndpointAuthMethodsSupported` (wire: `token_endpoint_auth_methods_supported`)	array<string>	TokenEndpointAuthMethodsSupported 는 `/oauth/token` 의 client 인증 방식.
`userinfoEndpoint` (wire: `userinfo_endpoint`)	string	UserInfoEndpoint 는 `/oauth/userinfo`.

`POST /api/v1/apps/{appID}/oauth-clients`

authPostApiV1AppsByAppIDOauthClients

path 의 앱에 새 OAuth client 를 등록한다. confidential client 는 raw client_secret 이 최초 응답에만 포함됨 (이후 미노출).

호출 권한: 앱 소유자 또는 같은 테넌트의 active tenant_admin (usecase 안에서 gate — 아니면 403).
appID 가 UUID 형식이 아니면 400. body JSON 형식이 아니면 400. type/auth_method/grant_type 형식 오류 시 400.
confidential client 인데 auth_method=none 이거나 그 반대면 400 (ErrAuthMethodMismatch / ErrConfidentialMissingSecret / ErrPublicHasSecret).
부수 효과: oauth_clients row insert. confidential 이면 client_secret 의 hash 만 저장 (응답의 raw 값을 클라이언트가 저장해야 함).

언어	호출
node	`sdk.apps.oauthClients(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthPostApiV1AppsByAppIDOauthClients(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authPostApiV1AppsByAppIDOauthClients(pathParams, query, body)` — 비동기: `authPostApiV1AppsByAppIDOauthClientsAsync(…)` → CompletableFuture
kotlin	`client.identity.authPostApiV1AppsByAppIDOauthClients(pathParams, query, body)` — suspend
python	`client.identity.auth_post_api_v1_apps_by_app_id_oauth_clients(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_post_api_v1_apps_by_app_id_oauth_clients(path_params: …, query: …, body: …)`
공통	`request("authPostApiV1AppsByAppIDOauthClients", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`allowed_grant_types`	array<string>	AllowedGrantTypes 는 허용된 grant_type. `authorization_code` / `refresh_token` / `urn:ietf:params:oauth:grant-type:device_code`.
`allowed_resources`	array<string>	AllowedResources 는 이 client 가 RFC 8707 resource 파라미터로 요청 가능한 audience 목록.
`allowed_scopes`	array<string>	AllowedScopes 는 이 client 가 요청 가능한 scope 목록.
`name`	string	Name 은 사용자에게 표시될 client 이름 (consent 화면 등).
`redirect_uris`	array<string>	RedirectURIs 는 허용된 redirect URI 화이트리스트. authorize 시 이 목록과 정확히 일치해야 함.
`token_endpoint_auth_method`	string	AuthMethod 는 `/oauth/token` client 인증 방식. `client_secret_basic` / `client_secret_post` / `none` (public).
`type`	string	Type 은 client 종류. `confidential` (server-side) / `public` (browser, mobile, CLI).

응답 — 201 · 등록된 client + client_secret (최초 한 번)

이름	타입	설명
`allowedGrantTypes` (wire: `allowed_grant_types`)	array<string>	AllowedGrantTypes 는 허용된 grant_type.
`allowedResources` (wire: `allowed_resources`)	array<string>	AllowedResources 는 허용된 RFC 8707 resource audience 목록.
`allowedScopes` (wire: `allowed_scopes`)	array<string>	AllowedScopes 는 허용된 scope 목록.
`appId` (wire: `app_id`)	string	AppID 는 client 가 속한 앱 UUID.
`clientSecret` (wire: `client_secret`)	string	ClientSecret 는 발급된 raw secret — confidential client 의 최초 응답에만 포함. 이후 조회에는 노출 X.
`id`	string	ID 는 client UUID.
`name`	string	Name 은 client 표시 이름.
`redirectUris` (wire: `redirect_uris`)	array<string>	RedirectURIs 는 허용된 redirect URI 화이트리스트.
`tokenEndpointAuthMethod` (wire: `token_endpoint_auth_method`)	string	TokenEndpointAuthMethod 는 `/oauth/token` 인증 방식.
`type`	string	Type 은 client 종류.

에러 status: 400 401 403 404 500 — 에러 처리

`GET /api/v1/me`

authGetApiV1Me

현재 access JWT 의 사용자 정보 + 활성 테넌트 멤버십 목록. CLI 가 device flow 후 처음 호출하고 SPA 가 부팅 시 호출.

호출 권한: 인증된 사용자 (RequireAuth). user_id 는 JWT 에서 추출 — body 신뢰 X.
사용자 row 가 없으면 (지웠는데 토큰은 남은 케이스) 404.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.identity.me(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthGetApiV1Me(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authGetApiV1Me(pathParams, query, body)` — 비동기: `authGetApiV1MeAsync(…)` → CompletableFuture
kotlin	`client.identity.authGetApiV1Me(pathParams, query, body)` — suspend
python	`client.identity.auth_get_api_v1_me(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_get_api_v1_me(path_params: …, query: …, body: …)`
공통	`request("authGetApiV1Me", pathParams, query, body)`

응답 — 200 · user + tenants

이름	타입	설명
`invitations`	array<object>
`tenants`	array<object>
`user`	object

에러 status: 401 404 500 — 에러 처리

`GET /api/v1/oauth-clients/{clientID}`

authGetApiV1OauthClientsByClientID

client 한 건 조회. client_secret 은 응답에 포함되지 않음 (생성 시 한 번만 노출).

호출 권한: 해당 앱 소유자 또는 같은 테넌트의 active tenant_admin (usecase 안에서 gate — 아니면 403).
clientID 가 UUID 형식이 아니면 400. client 가 없으면 404.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.identity.systemOAuthClients(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthGetApiV1OauthClientsByClientID(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authGetApiV1OauthClientsByClientID(pathParams, query, body)` — 비동기: `authGetApiV1OauthClientsByClientIDAsync(…)` → CompletableFuture
kotlin	`client.identity.authGetApiV1OauthClientsByClientID(pathParams, query, body)` — suspend
python	`client.identity.auth_get_api_v1_oauth_clients_by_client_id(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_get_api_v1_oauth_clients_by_client_id(path_params: …, query: …, body: …)`
공통	`request("authGetApiV1OauthClientsByClientID", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`clientID` 필수	string	OAuth client UUID

응답 — 200 · client

이름	타입	설명
`allowedGrantTypes` (wire: `allowed_grant_types`)	array<string>	AllowedGrantTypes 는 허용된 grant_type.
`allowedResources` (wire: `allowed_resources`)	array<string>	AllowedResources 는 허용된 RFC 8707 resource audience 목록.
`allowedScopes` (wire: `allowed_scopes`)	array<string>	AllowedScopes 는 허용된 scope 목록.
`appId` (wire: `app_id`)	string	AppID 는 client 가 속한 앱 UUID.
`id`	string	ID 는 client UUID.
`name`	string	Name 은 client 표시 이름.
`redirectUris` (wire: `redirect_uris`)	array<string>	RedirectURIs 는 허용된 redirect URI 화이트리스트.
`tokenEndpointAuthMethod` (wire: `token_endpoint_auth_method`)	string	TokenEndpointAuthMethod 는 `/oauth/token` 인증 방식.
`type`	string	Type 은 client 종류.

에러 status: 400 401 403 404 500 — 에러 처리

`DELETE /api/v1/oauth/clients/{clientID}/grants/me`

authDeleteApiV1OauthClientsByClientIDGrantsMe

현재 사용자가 path client 에 부여한 consent + 활성 refresh token 을 회수한다 ("이 앱과의 연결 끊기" 버튼).

호출 권한: 인증된 사용자 (RequireAuth via cookie session). user_id 는 JWT 에서 추출.
clientID 가 UUID 형식이 아니면 400.
Idempotent — grant 가 없거나 이미 회수된 상태에서도 204.
부수 효과: 해당 (user, client) 의 consent row + 활성 refresh token 모두 revoked 로 마킹.

언어	호출
node	`sdk.identity.oauth.grants(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthDeleteApiV1OauthClientsByClientIDGrantsMe(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authDeleteApiV1OauthClientsByClientIDGrantsMe(pathParams, query, body)` — 비동기: `authDeleteApiV1OauthClientsByClientIDGrantsMeAsync(…)` → CompletableFuture
kotlin	`client.identity.authDeleteApiV1OauthClientsByClientIDGrantsMe(pathParams, query, body)` — suspend
python	`client.identity.auth_delete_api_v1_oauth_clients_by_client_id_grants_me(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_delete_api_v1_oauth_clients_by_client_id_grants_me(path_params: …, query: …, body: …)`
공통	`request("authDeleteApiV1OauthClientsByClientIDGrantsMe", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`clientID` 필수	string	OAuth client UUID

응답 — 204 · 회수 완료 (no content)

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 500 — 에러 처리

`POST /auth/logout`

authPostAuthLogout

_hub_refresh 의 refresh token 을 회수하고 hub cookie 3종을 제거한다.

호출 권한: public — refresh cookie 가 없어도 idempotent (cookie clear 만 수행).
refresh token 회수 실패 (이미 회수 등) 는 silent 처리. 응답은 언제나 204.
부수 효과: refresh token 회수 (DB), _hub_access/_hub_refresh/_hub_hint cookie 제거.

언어	호출
node	`sdk.identity(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthPostAuthLogout(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authPostAuthLogout(pathParams, query, body)` — 비동기: `authPostAuthLogoutAsync(…)` → CompletableFuture
kotlin	`client.identity.authPostAuthLogout(pathParams, query, body)` — suspend
python	`client.identity.auth_post_auth_logout(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_post_auth_logout(path_params: …, query: …, body: …)`
공통	`request("authPostAuthLogout", pathParams, query, body)`

응답 — 204 · 로그아웃 성공 (cookie 제거됨)

본문 없음 → SDK 는 빈 map {} 반환

`POST /auth/refresh`

authPostAuthRefresh

_hub_refresh cookie 의 refresh token 을 회전시키고 새 access JWT 를 발급한다.

호출 권한: _hub_refresh cookie (path=/auth/refresh) 가 있는 브라우저. cookie 가 없거나 만료/회수면 401.
호출 시 refresh token 이 회전 (이전 token 은 invalidate). 토큰 도난 탐지 목적.
401 응답 시 _hub_access + _hub_refresh cookie 가 함께 제거됨.
부수 효과: 새 _hub_access / _hub_refresh cookie set. JSON body 에 새 access token 동봉.

언어	호출
node	`sdk.identity(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthPostAuthRefresh(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authPostAuthRefresh(pathParams, query, body)` — 비동기: `authPostAuthRefreshAsync(…)` → CompletableFuture
kotlin	`client.identity.authPostAuthRefresh(pathParams, query, body)` — suspend
python	`client.identity.auth_post_auth_refresh(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_post_auth_refresh(path_params: …, query: …, body: …)`
공통	`request("authPostAuthRefresh", pathParams, query, body)`

응답 — 200 · 새 access JWT body + Set-Cookie

이름	타입	설명
`accessToken` (wire: `access_token`)	string	AccessToken 은 발급된 access JWT. SPA 가 body 로 받고 싶을 때 사용.
`expiresIn` (wire: `expires_in`)	integer	ExpiresIn 은 access token 만료까지 초.
`tokenType` (wire: `token_type`)	string	TokenType 은 항상 `Bearer`.

에러 status: 401 — 에러 처리

`GET /oauth/userinfo`

authGetOauthUserinfo

Access token 의 사용자 claim 을 scope 별로 필터해서 반환.

호출 권한: OAuth access token (Authorization: Bearer). /oauth/token 으로 발급된 토큰. AX Hub 의 BearerAuth (cookie-issued JWT) 와는 별 인증 — WWW-Authenticate 헤더로 RFC 6750 응답.
토큰 누락 시 401 invalid_request. 검증 실패 (만료/회수/형식 오류) 시 401 invalid_token.
scope 에 따라 응답 claim 이 달라짐: openid (sub), profile (name 등), email (email).
부수 효과 없음 (read-only).

언어	호출
node	`sdk.identity(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Identity().AuthGetOauthUserinfo(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.identity().authGetOauthUserinfo(pathParams, query, body)` — 비동기: `authGetOauthUserinfoAsync(…)` → CompletableFuture
kotlin	`client.identity.authGetOauthUserinfo(pathParams, query, body)` — suspend
python	`client.identity.auth_get_oauth_userinfo(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.identity.auth_get_oauth_userinfo(path_params: …, query: …, body: …)`
공통	`request("authGetOauthUserinfo", pathParams, query, body)`

응답 — 200 · OIDC claims (scope-filtered)

스키마 미정의 — camelize 된 map 그대로 반환

에러 status: 401 500 — 에러 처리