REST API 사용

이 문서에서는 Identity Platform REST API를 사용하여 사용자 로그인 및 토큰 작업 등의 일반적인 사용자 작업을 수행하는 방법을 보여줍니다.

시작하기 전에

REST API를 사용하려면 Identity Platform API 키가 필요합니다. 키를 가져오려면 다음 안내를 따르세요.

  1. Google Cloud 콘솔에서 ID 공급업체 페이지로 이동합니다.
    ID 공급업체 페이지로 이동

  2. 애플리케이션 설정 세부정보를 클릭합니다.

  3. apiKey 필드를 복사합니다.

모든 API 호출에는 HTTPS가 필요합니다.

API 호출

커스텀 토큰을 ID와 갱신 토큰으로 교환

signInWithCustomToken 엔드포인트에 HTTP POST 요청을 실행하여 커스텀 인증 토큰을 ID 및 갱신 토큰으로 교환할 수 있습니다.

메서드: POST

콘텐츠 유형: application/json

엔드포인트 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]
 요청 본문 페이로드
속성 이름 유형 설명
token 문자열 ID 및 갱신 토큰 쌍을 생성할 Identity Platform 커스텀 토큰입니다.
returnSecureToken 불리언 ID 및 갱신 토큰 반환 여부입니다. 항상 참이어야 합니다.
tenantId 문자열 사용자가 로그인하는 테넌트 ID입니다. 멀티테넌시에서만 사용됩니다.
토큰의 tenant_id와 일치해야 합니다.
커스텀 토큰 클레임
속성 이름 설명
alg 알고리즘 RS256이어야 합니다.
iss 발급자 프로젝트의 서비스 계정 이메일 주소
sub 제목 프로젝트의 서비스 계정 이메일 주소
aud 대상 https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit
iat 발급 시간 UNIX epoch를 기준으로 하는 현재 시간(초)
exp 만료 시간 Unix epoch를 기준으로 하는 토큰 만료 시간(초). iat보다 최대 3,600초 길어질 수 있습니다.
참고: 이 항목은 커스텀 토큰 자체의 만료 시간만 제어합니다. signInWithCustomToken()으로 사용자가 로그인한 후에는 세션이 무효화되거나 사용자가 로그아웃할 때까지 기기에서 로그인 상태가 유지됩니다.
uid 사용자 ID 사용자의 고유 식별자(1~36자)
tenant_id 테넌트 ID 사용자가 로그인하는 테넌트의 식별자입니다.
클레임(선택) 보안 규칙의 auth 또는 request.auth 변수에 포함할 선택적인 커스텀 클레임
응답 페이로드
속성 이름 유형 설명
idToken 문자열 제공된 커스텀 토큰에서 생성된 Identity Platform ID 토큰
refreshToken 문자열 제공된 커스텀 토큰에서 생성된 Identity Platform 갱신 토큰
expiresIn 문자열 ID 토큰이 만료될 때까지 남은 시간(초)입니다.

샘플 요청 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"token":"[CUSTOM_TOKEN]","returnSecureToken":true}'

성공적인 요청은 200 OK HTTP 상태 코드로 표시됩니다. 응답에는 Identity Platform ID 토큰과 커스텀 토큰과 관련된 갱신 토큰이 포함됩니다.

샘플 응답

{
  "idToken": "[ID_TOKEN]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

일반적인 오류 코드

  • INVALID_CUSTOM_TOKEN: 커스텀 토큰 형식이 잘못되었거나 어떠한 이유로 유효하지 않은 토큰입니다(예: 만료된 토큰, 잘못된 서명 등).
  • CREDENTIAL_MISMATCH: 커스텀 토큰이 다른 Google Cloud 프로젝트에 해당합니다.

갱신 토큰을 ID 토큰으로 교환

securetoken.googleapis.com 엔드포인트에 HTTP POST 요청을 실행하여 Identity Platform ID 토큰을 갱신할 수 있습니다.

메서드: POST

콘텐츠 유형: application/x-www-form-urlencoded

엔드포인트 
https://securetoken.googleapis.com/v1/token?key=[API_KEY]
 요청 본문 페이로드
속성 이름 유형 설명
grant_type 문자열 갱신 토큰의 부여 유형으로, 항상 'refresh_token'입니다.
refresh_token 문자열 Identity Platform 갱신 토큰입니다.
응답 페이로드
속성 이름 유형 설명
expires_in 문자열 ID 토큰이 만료될 때까지 남은 시간(초)입니다.
token_type 문자열 갱신 토큰의 유형으로, 항상 'Bearer'입니다.
refresh_token 문자열 요청에 제공된 Identity Platform 갱신 토큰 또는 새 갱신 토큰입니다.
id_token 문자열 Identity Platform ID 토큰
user_id 문자열 제공된 ID 토큰에 해당하는 uid
project_id 문자열 Google Cloud 프로젝트 ID입니다.

샘플 요청 

curl 'https://securetoken.googleapis.com/v1/token?key=[API_KEY]' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&refresh_token=[REFRESH_TOKEN]'

성공적인 요청은 200 OK HTTP 상태 코드로 표시됩니다. 응답에는 새 Identity Platform ID 토큰과 갱신 토큰이 포함됩니다.

샘플 응답

{
  "expires_in": "3600",
  "token_type": "Bearer",
  "refresh_token": "[REFRESH_TOKEN]",
  "id_token": "[ID_TOKEN]",
  "user_id": "tRcfmLH7o2XrNELi...",
  "project_id": "1234567890"
}

일반적인 오류 코드

  • TOKEN_EXPIRED: 사용자의 사용자 인증 정보가 더 이상 유효하지 않습니다. 사용자가 다시 로그인해야 합니다.
  • USER_DISABLED: 관리자가 사용자 계정을 사용 중지했습니다.
  • USER_NOT_FOUND: 갱신 토큰에 해당하는 사용자를 찾을 수 없습니다. 사용자가 삭제되었을 수 있습니다.
  • API 키가 올바르지 않습니다. 유효한 API 키를 전달하세요. (잘못된 API 키 제공)
  • INVALID_REFRESH_TOKEN: 잘못된 갱신 토큰이 제공됩니다.
  • 잘못된 JSON 페이로드가 수신되었습니다. 알 수 없는 이름 \"refresh_tokens \": 쿼리 매개변수를 결합할 수 없습니다. 요청 메시지에서 'refresh_tokens' 필드를 찾을 수 없습니다.
  • INVALID_GRANT_TYPE: 지정된 부여 유형이 잘못되었습니다.
  • MISSING_REFRESH_TOKEN: 갱신 토큰이 제공되지 않았습니다.
  • PROJECT_NUMBER_MISMATCH: 갱신 토큰의 프로젝트 번호가 제공된 API 키의 프로젝트 번호와 일치하지 않습니다.

이메일 / 비밀번호로 가입

인증 signupNewUser 엔드포인트에 HTTP POST 요청을 실행하여 새 이메일 및 비밀번호 사용자를 만들 수 있습니다.

메서드: POST

콘텐츠 유형: application/json

엔드포인트 
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY