Verify API

PASS식 1회성 SSAFY 인증

외부 앱의 로그인은 유지하면서 이번 거래에서 사용자가 SSAFY 구성원인지 확인합니다. 매 거래마다 Mattermost DM 코드 인증을 요구합니다.

Quickstart Error Codes

Canonical issuer

Verify API의 issuer는 문서를 연 도메인이 아니라 아래 canonical 값으로 고정합니다.

Canonical issuer?callback iss, JWT iss, JWKS 기준값입니다.: https://verify.myknow.xyz
Canonical API base URL?authorize, token, jwks, Hosted SDK URL을 만들 때 사용합니다.: https://verify.myknow.xyz
Canonical SDK URL?브라우저, React, Vue 연동은 이 경로만 사용합니다.: https://verify.myknow.xyz/sdk/ssafy-verify.js
Compatibility alias?외부 사용자가 없는 pre-public rename이므로 legacy alias를 제공하지 않습니다.: none
Exact match rule?다르면 token exchange를 시작하지 않습니다.: callback.iss === "https://verify.myknow.xyz"

Flow summary

Verify API는 외부 앱 로그인과 별개로 이번 거래의 SSAFY 인증 여부만 확인합니다.

1. authorize

외부 앱이 state와 PKCE challenge를 만들고 사용자를 /verify/authorize로 보냄

2. consent

SSAFY Verify가 앱 이름, redirect domain, 제공 정보를 보여줌

3. DM code

사용자가 Mattermost DM으로 받은 6자리 코드를 입력

4. callback

외부 앱 redirect_uri로 code, state, iss 전달

5. token

외부 앱 서버가 /verify/token에서 verification_token 교환

6. verify

JWT 서명과 iss, aud, exp, sub, client_id, verified, auth_time, amr, acr 확인 후 최소 claim 저장

v1 공식 범위

SSAFY Verify v1은 본인인증만 공식 지원합니다. 외부 앱 로그인을 SSAFY Verify로 대체하는 OIDC 연동은 v2에서 지원 예정입니다.

Authorize

사용자를 SSAFY Verify 인증 화면으로 이동시키는 endpoint입니다.

Endpoint: GET /verify/authorize
Success callback: redirect_uri?code=...&state=...&iss=...
Failure callback: redirect_uri?error=...&error_code=...&request_id=...&state=...

Query parameters

client_id?SSAFY Verify가 어떤 외부 앱의 요청인지 식별하는 공개 값입니다.: 필수. 승인된 Verify client id
redirect_uri?callback을 받을 URL입니다. 등록값과 문자 단위로 같아야 합니다.: 필수. client에 등록된 redirect URI와 exact match
scope?외부 앱이 받을 SSAFY claim 범위를 공백으로 구분해 요청합니다.: 필수. ssafy.verify 포함. 예: ssafy.verify ssafy.affiliation ssafy.name
state?CSRF와 callback 혼동을 막기 위해 요청 시작 값과 callback 값을 비교합니다.: 필수. 외부 앱이 생성하고 callback에서 비교하는 난수
code_challenge?code_verifier를 SHA-256으로 변환한 공개 검증값입니다.: 필수. PKCE S256 challenge
code_challenge_method?plain 방식은 허용하지 않습니다. 항상 S256을 사용합니다.: 필수. S256만 허용
nonce?Verify v1에서는 선택값입니다. v2 OIDC 로그인 nonce와 구분하세요.: 선택. 거래 추적용 난수

authorize-url.txt브라우저 이동 URL 예시

https://verify.myknow.xyz/verify/authorize?
  client_id=client_example_public
  &redirect_uri=https%3A%2F%2Fpartner.example.com%2Fssafy%2Fcallback
  &scope=ssafy.verify%20ssafy.affiliation%20ssafy.name
  &state=random_state_from_partner
  &code_challenge=pkce_challenge
  &code_challenge_method=S256

Callback

사용자가 인증을 완료하면 SSAFY Verify가 등록된 redirect_uri로 이동합니다.

Success fields: code, state, iss
Failure fields: error, error_code, request_id, state
state: 외부 앱이 authorize 시작 시 만든 값과 반드시 비교
iss: https://verify.myknow.xyz 와 정확히 일치해야 token exchange 진행
code: 브라우저에 저장하지 않고 즉시 서버 route로 전달

Callback fields

code?즉시 서버 route로 전달하고 저장하지 않습니다.: 성공 시 전달되는 1회성 callback code
state?저장해 둔 state와 정확히 일치해야 합니다.: authorize 시작 시 외부 앱이 만든 값
iss?https://verify.myknow.xyz 와 일치할 때만 token exchange를 시작합니다.: SSAFY Verify issuer
error?예: access_denied. 사용자 취소와 요청 오류를 구분합니다.: 실패 시 OAuth 스타일 error
error_code?개발자 처리와 운영 문의에 사용합니다.: SSAFY Verify의 안정적인 내부 error code
request_id?사용자에게 작게 표시하고 운영자에게 전달할 수 있습니다.: 실패 추적용 request id

callback-url.txt성공 callback 예시

https://partner.example.com/ssafy/callback?
  code=code_from_ssafy_verify
  &state=random_state_from_partner
  &iss=https%3A%2F%2Fverify.myknow.xyz

Token

callback code를 verification_token JWT로 교환합니다. public client는 client_secret을 보내지 않습니다.

Endpoint: POST /verify/token
Content-Type: application/x-www-form-urlencoded
Cache: no-store 응답

Body parameters

grant_type?Verify API token exchange에서는 authorization_code가 아니라 verification_code를 사용합니다.: 필수. verification_code
code?짧게 유효한 1회성 code입니다. URL, 로그, 브라우저 저장소에 보관하지 않습니다.: 필수. callback query의 code
client_id?authorize 요청의 client_id와 같은 값이어야 합니다.: 필수. 승인된 client id
client_secret?public client, 브라우저, 모바일 앱에서는 절대 사용하지 않습니다.: confidential client에서만 서버에서 전송
code_verifier?code_challenge를 만들 때 사용한 원본 난수입니다. token exchange 직후 폐기합니다.: 필수. authorize 시작 시 만든 PKCE verifier

curl/verify/token 교환 요청

curl -X POST https://verify.myknow.xyz/verify/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=verification_code" \
  -d "client_id=client_example_public" \
  -d "code=code_from_callback" \
  -d "code_verifier=pkce_verifier_from_browser"

success.json성공 응답

{
  "verification_token": "jwt_placeholder",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "ssafy.verify ssafy.affiliation ssafy.name",
  "result": {
    "verification_id": "verification_id_placeholder",
    "verified": true,
    "sub": "pairwise_subject_placeholder",
    "auth_time": "2026-06-18T00:00:00.000Z"
  }
}

Success response fields

verification_token?서버에서 JWKS로 검증한 뒤 원문은 저장하지 않습니다.: 서명된 Verify JWT
token_type?응답 토큰의 타입입니다.: Bearer
expires_in?Verify token은 5분 이하의 짧은 수명을 가집니다.: 초 단위 만료 시간
scope?요청 scope가 아니라 실제 승인된 scope 기준입니다.: 승인되어 반영된 scope 문자열
result?result.auth_time은 ISO 8601 문자열입니다. JWT auth_time claim은 NumericDate seconds입니다.: 검증 결과 요약 객체

auth_time 타입

`/verify/token` JSON의 `result.auth_time`은 ISO 8601 문자열입니다. `verification_token` JWT claim의 `auth_time`은 JWT 표준 NumericDate seconds입니다. 파트너 서버가 앱에 내려주는 `authTime`은 JWT claim에서 읽은 seconds 값으로 통일하는 것을 권장합니다.

error.json실패 응답

{
  "ok": false,
  "error": {
    "code": "PKCE_VERIFICATION_FAILED",
    "message": "PKCE 검증에 실패했습니다.",
    "request_id": "req_placeholder"
  }
}

Scope별 반환 claim

scope는 최소한으로 요청합니다. 이름과 프로필 이미지는 별도 scope입니다.

Scope	Required	Claims	Nullable	사용 조건
ssafy.verify	yes	verified, sub, auth_time, verification_id, amr, acr	no	모든 Verify 연동에 필요합니다. 외부 앱은 최소 인증 결과만 저장하세요.
ssafy.affiliation	no	ssafy_cohort, ssafy_campus, ssafy_region	yes	기수, 캠퍼스, 지역 기준으로 혜택이나 권한을 나눌 때만 요청합니다.
ssafy.name	no	name	yes	사용자 이름 표시나 기존 회원 정보 매칭이 필요할 때만 요청합니다.
ssafy.profile_image	no	picture	yes	프로필 이미지를 화면에 표시할 때만 요청합니다.
ssafy.role	no	ssafy_role, ssafy_role_name	yes	교육생/운영진 등 역할 기반 기능이 있을 때만 요청합니다.
ssafy.mattermost_id	no	ssafy_mattermost_user_id	yes	기존 Mattermost 인증 프로젝트의 계정 매핑이 필요할 때만 요청합니다.

Verification token claims

외부 앱 서버는 verification_token의 서명과 claim을 검증한 뒤 세션이나 DB에 최소 결과만 저장합니다.

iss?토큰 발급자가 SSAFY Verify인지 검증합니다.: SSAFY Verify issuer
aud?이 토큰을 사용할 외부 앱 client_id와 일치해야 합니다.: client_id
sub?앱별로 분리된 사용자 식별자입니다. 앱 간 추적에 쓰지 않습니다.: client별 pairwise subject
exp?현재 시각보다 과거면 즉시 거절합니다.: 만료 시각. Verify token은 5분 이하
verification_id?문의나 감사 추적에 사용하는 거래 식별자입니다.: 이번 Verify 거래 id
verified?값이 true가 아니면 인증 완료로 처리하지 않습니다.: 항상 true
auth_time?인증이 완료된 시각입니다. 앱 내부 authTime도 이 seconds 값을 권장합니다.: JWT NumericDate seconds
amr?Mattermost DM 코드 방식으로 인증했음을 나타냅니다.: mattermost_dm
acr?SSAFY Verify v1의 보증 수준을 나타내는 고정 claim입니다.: urn:ssafy:verify:assurance:mattermost-team-dm:v1
ssafy_*?기수/캠퍼스/지역은 ssafy.affiliation, 이름은 ssafy.name, 이미지는 ssafy.profile_image, Mattermost id는 ssafy.mattermost_id가 승인된 경우에만 포함됩니다.: 승인된 scope에 따라 제공되는 SSAFY claim
ssafy_mattermost_user_id?ssafy.mattermost_id scope가 승인된 경우에만 포함됩니다. 기존 Mattermost 인증 프로젝트의 계정 매핑에만 사용하세요.: Mattermost 고유 user id

Error JSON 경계

SSAFY Verify 원본 오류와 파트너 앱이 자기 frontend에 내려주는 응답 형식을 구분하세요.

SSAFY Verify original?/verify/token에서 받은 원본 실패 응답입니다. token, code, raw provider response는 포함하지 않습니다.: ok: false, error.code, error.message, error.request_id
Partner app response?Quickstart 예제가 자기 frontend에 내려주는 간단한 응답입니다. 원본 error.code를 errorCode로 매핑합니다.: ok: false, errorCode, requestId

Security notes

callback code와 verification_token은 로그에 남기지 않습니다.
redirect URI는 등록값과 exact match여야 합니다.
callback iss가 SSAFY Verify issuer와 다르면 token exchange를 시작하지 않습니다.
PKCE verifier는 token exchange 직후 폐기합니다.
이름은 ssafy.name scope가 승인된 경우에만 사용합니다.
프로필 이미지는 ssafy.profile_image scope가 승인된 경우에만 사용합니다.
JWT는 iss, aud, exp, sub, client_id, verified, auth_time, amr, acr를 모두 검증합니다.
기존 Mattermost 인증 계정 매핑이 필요할 때만 ssafy.mattermost_id를 요청합니다.
Mattermost user id는 raw user object의 id이며, username은 변경 가능한 보조 표시값으로만 취급합니다.
cohort는 raw user object가 아니라 수집한 Mattermost team context 기준으로 판단합니다.