Developer Docs
SSAFY 구성원 플랫폼 API 문서
SSAFY Verify는 단일 인증 API가 아니라 SSAFY 구성원 플랫폼 API입니다.User Auth로 구성원 여부를 확인하고, Server API로 프로필 조회, 디렉터리 lookup, Mattermost 알림을 backend에서 위임합니다.
연동 경로 선택
목표에 맞는 시작 문서를 먼저 고르세요.Firebase 콘솔처럼 같은 App 아래에서 User Auth와 Server API credential을 함께 운영하는 흐름입니다.
User Auth
구성원 인증만 붙이기
외부 서비스 로그인/가입 단계에서 SSAFY 구성원 여부와 기수, 캠퍼스, 트랙을 확인합니다.
Server API
Backend에서 프로필 조회
서버가 pairwise sub, Mattermost user id, username/cohort 기준으로 SSAFY profile snapshot을 조회합니다.
Notification
Mattermost DM 발송
승인된 template/purpose 조합으로 단건 또는 최대 25명 batch Mattermost DM을 발송합니다.
Mobile
모바일/네이티브 앱 연결
WebView가 아니라 시스템 브라우저, Universal Link, verified App Link 기반으로 인증 흐름을 연결합니다.
Canonical issuer
Verify 연동 설정은 아래 issuer 하나만 사용합니다.
https://verify.myknow.xyz
iss가https://verify.myknow.xyz와 exact match일 때만 token exchange를 시작하세요. SDK/API base URL과 JWKS 기준값도 같은 issuer를 사용합니다.콘솔 운영 루프
App 단위로 신청, 검증, 테스트, 운영 추적을 반복합니다.공개 문서는 흐름만 안내하고 secret과 실행 결과는 인증된 Developer Console에서 다룹니다.
App과 credential 분리
Developer Console하나의 App 아래에 User Auth public client와 Server API confidential credential을 분리해 등록합니다.
App statusclient_idapproved scopesLaunch readiness 확인
Quickstartredirect URI, allowed origin, scope, template, webhook, team 구성을 readiness board에서 먼저 정리합니다.
redirect exact matchPKCE S256template approval서비스 구성원 API 테스트
Server API소유자와 공동 개발자를 안전한 테스트 대상으로 선택해 profile, directory, Mattermost notification 호출을 검증합니다.
active membersapi-test idempotencyside-effect confirmrequest_id 운영 추적
Error Codes실패 응답의 request_id를 기준으로 request logs, security events, audit logs와 runbook을 함께 확인합니다.
error_coderequest_idredacted logs문서 흐름
처음 연동은 User Auth로 구성원 인증을 붙이고, backend 기능이 필요해지면 같은 App 아래에 Server API credential을 추가합니다.
User Auth 빠른 시작
인증 화면과 서버 token exchange route로 SSAFY 구성원 확인을 구성합니다.
플랫폼별 적용
React, Vue, Backend, 모바일 앱 연결 흐름을 정리합니다.
Verify API
authorize, callback, token exchange, verification JWT 레퍼런스입니다.
Server API
client_credentials, 프로필 조회, 디렉터리 lookup, Mattermost 알림 API입니다.
Error Codes
error_code별 원인, 사용자 메시지, 개발자 조치를 정리합니다.
AI용 문서
코딩 에이전트에게 넘길 링크와 구현 지시문입니다.
OIDC는 v2에서 지원 예정
SSAFY Verify v1은 User Auth와 Server API를 공식 지원합니다.외부 앱 로그인을 SSAFY Verify로 대체하는 OIDC provider 문서는 현재 public quickstart 범위에서 제외합니다.
이미 구현된 OIDC endpoint는 향후 호환성을 위해 유지하지만, 신규 연동은/verify/authorize와/verify/token를 먼저 사용하세요. backend에서 SSAFY 프로필, 디렉터리, Mattermost 알림 위임이 필요하면/docs/server-api의 /v1/* 계약을 사용합니다.
User Auth 준비물
구성원 인증과 verification_token 교환을 위해 필요한 값입니다.
client_idDeveloper Portal App 아래에서 승인받은 credential client id
redirect_uriclient 설정에 exact match로 등록된 callback URL. 승인 후 소유자가 수정 가능
scopessafy.verify는 필수. 기수/캠퍼스/지역은 ssafy.affiliation, 트랙은 ssafy.track, 이름은 ssafy.name, 이미지는 ssafy.profile_image 추가
Mattermost id기존 Mattermost 인증 프로젝트의 계정 매핑이 필요할 때만 ssafy.mattermost_id 요청
PKCE S256브라우저에서 verifier를 만들고 서버 token exchange까지 보존
state요청 시작 시 만든 값을 callback에서 반드시 비교
Server API 준비물
partner backend가 SSAFY 프로필과 Mattermost 알림을 SSAFY Verify에 위임할 때 필요한 값입니다.
Server API credential같은 App 아래에서 approved confidential credential 발급
client_secret생성 직후 1회만 확인하고 backend secret 저장소에 보관
server scopesssafy.profile.read, ssafy.directory.lookup, ssafy.notify.mattermost.send/status 등 필요한 권한 승인
template/purposeMattermost 알림은 Admin이 승인한 template과 purpose만 사용
Bearer tokenbackend에서 /v1/server/token client_credentials 교환 후 /v1/* 호출
핵심 endpoints
/verify/authorizeGET사용자가 SSAFY 인증을 진행하는 화면
/verify/tokenPOSTcallback code를 verification_token으로 교환
/v1/server/tokenPOSTServer API access token 발급
/v1/ssafy-members/{sub}/profileGETpairwise subject 기준 SSAFY 프로필 조회
/v1/mattermost-users/profiles/batchPOST최대 500개 Mattermost user id 일괄 프로필 조회
/v1/mattermost-usersGETMattermost username/cohort exact lookup
/v1/notifications/mattermostPOST승인 템플릿 기반 Mattermost DM 단건 즉시 발송
/v1/notifications/mattermost/batchPOST최대 25명 Mattermost DM batch 발송