인증

인증 방식

씨미 OpenAPI는 두 가지 인증 방식을 지원합니다.

Client ID/Secret 사용 예시

GET /api/openapi/open/v1/channels?channelIds=12345
Client-Id: {clientId}
Client-Secret: {clientSecret}

Access Token 사용 예시

GET /api/openapi/open/v1/users/me
Authorization: Bearer {accessToken}

애플리케이션 등록

API를 사용하려면 먼저 개발자 포탈에서 애플리케이션을 등록해야 합니다.

1. 개발자 포탈(/applications)에 로그인합니다.
2. + 새 애플리케이션 버튼을 눌러 애플리케이션을 생성합니다.
3. 생성된 Client ID와 Client Secret을 안전하게 보관합니다.
4. OAuth 인증에 사용할 Redirect URI를 설정합니다.

Client Secret은 외부에 노출되지 않도록 주의하세요. 서버 사이드 코드에서만 사용하는 것을 권장합니다.

애플리케이션 이름 규칙

OAuth 2.0 Authorization Code Flow

사용자 권한이 필요한 API를 호출하려면 OAuth 2.0 Authorization Code Flow를 통해 Access Token을 발급받아야 합니다.

전체 흐름

1. 사용자를 씨미 인증 페이지로 리디렉트
   → https://ci.me/auth/openapi/account-interlock
     ?clientId={clientId}
     &redirectUri={redirectUri}
     &state={state}

2. 사용자가 권한 승인

3. 씨미가 Redirect URI로 Authorization Code 전달
   → https://your-app.com/callback?code={authorizationCode}&state={state}

4. Authorization Code로 Access Token 발급
   POST /api/openapi/auth/v1/token
   {
     "grantType": "authorization_code",
     "clientId": "{clientId}",
     "clientSecret": "{clientSecret}",
     "code": "{authorizationCode}"
   }

5. Access Token으로 API 호출
   Authorization: Bearer {accessToken}

6. 토큰 만료 시 Refresh Token으로 갱신
   POST /api/openapi/auth/v1/token
   {
     "grantType": "refresh_token",
     "clientId": "{clientId}",
     "clientSecret": "{clientSecret}",
     "refreshToken": "{refreshToken}"
   }

토큰 유효 시간

Refresh Token은 1회용입니다 (Rotation). refresh_token 그랜트로 토큰을 갱신하면 응답으로 새 accessToken과 **새 refreshToken**이 함께 발급되고, 기존 refreshToken은 즉시 무효화됩니다. 따라서 클라이언트는 갱신 응답에서 받은 새 refreshToken을 반드시 저장하고 다음 갱신에 사용해야 합니다. 이전 refreshToken을 재사용하면 401(Refresh token has already been used)이 발생합니다. 새 Refresh Token의 유효 기간도 갱신 시점 기준 6개월로 다시 시작됩니다.

토큰 발급 API

POST /api/openapi/auth/v1/token

응답:

{
  "code": 200,
  "message": null,
  "content": {
    "accessToken": "eyJhbGciOiJ...",
    "refreshToken": "dGhpcyBpc...",
    "tokenType": "Bearer",
    "expiresIn": "86400",
    "scope": "READ:USER READ:CHANNEL"
  }
}

위 성공 응답은 { code, message, content } 래퍼 형식입니다. 반면 인증 실패(401) 등 에러는 { statusCode, message, error } 형태로 내려가므로 성공 응답과 에러 응답의 구조가 다릅니다. 응답 처리 시 HTTP 상태 코드로 성공/실패를 먼저 판별하세요.

토큰 발급/갱신 시 401 처리

토큰 발급(authorization_code) 또는 갱신(refresh_token) 요청이 인증에 실패하면 HTTP 401 Unauthorized와 함께 다음과 같은 에러 응답이 반환됩니다.

{
  "statusCode": 401,
  "message": "Refresh token has already been used",
  "error": "Unauthorized"
}

주요 401 케이스:

회복 절차

• refresh_token 갱신에서 401을 받으면, 보관 중인 유효한 Refresh Token으로 재시도합니다. (직전 갱신 응답에서 받은 최신 Refresh Token만 유효합니다.)
• 유효한 Refresh Token이 없거나 재시도도 401이면, 처음부터 OAuth 2.0 Authorization Code Flow로 재인증하여 새 토큰을 발급받아야 합니다.

토큰 취소 API

POST /api/openapi/auth/v1/token/revoke

취소에 성공하면 응답 바디 없이 HTTP 200 OK만 반환됩니다. tokenTypeHint로 지정한 토큰뿐 아니라 해당 인증에 연결된 Access/Refresh Token이 모두 함께 취소되고, 인증 상태도 REVOKED로 변경됩니다.

존재하지 않거나 이미 취소된 토큰, 또는 다른 애플리케이션의 토큰을 취소하려 하면 HTTP 401 Unauthorized가 반환됩니다.

Scope 설정

애플리케이션이 요청할 Scope는 개발자 포탈에서 직접 고를 수 있습니다.

1. /applications에서 애플리케이션을 선택합니다.
2. 수정을 눌러 필요한 Scope만 체크합니다.
3. 저장하면 이후 사용자 동의 화면에 체크한 Scope만 표시됩니다.

새로 만든 애플리케이션은 모든 Scope가 활성화된 상태로 시작합니다. 실제로 쓰는 것만 남기는 편이 사용자 동의율에 유리합니다.

변경 사항이 적용되는 시점

Scope는 사용자가 동의하는 시점에 그 사용자의 권한으로 복사되고, 발급되는 Access Token에 그대로 새겨집니다. 그래서 Scope를 바꿔도 이미 동의한 사용자에게 즉시 반영되지는 않습니다.

Scope를 추가했다면 기존 사용자를 다시 인증 페이지로 보내야 합니다.

권한이 부족할 때

토큰에 없는 Scope가 필요한 API를 호출하면 HTTP 401 Unauthorized가 반환됩니다.

Insufficient scope: WRITE:LIVE_CHAT required

토큰이 실제로 어떤 Scope를 갖고 있는지는 토큰 발급 응답의 scope 필드에서 확인할 수 있습니다.

Scope 레퍼런스

Scope는 Access Token이 접근할 수 있는 API 범위를 정의합니다.