manage-api

Auth0 Management API

Auth0 Management API는 사용자·애플리케이션·테넌트 같은 것들을 프로그래밍 방식으로 관리할 수 있게 해 주는 엔드포인트 모음이에요. 백엔드 서버나 신뢰할 수 있는 파티(trusted parties)가 쓰도록 만들어진 API라서, Auth0 대시보드에서 할 수 있는 거의 모든 일을 코드로도 할 수 있어요. 프론트엔드 같은 신뢰할 수 없는 쪽에서 쓰는 공개용 Authentication API와는 별개로, 이 API는 조심히 다뤄야 하는 권한 높은 작업을 담당해요. 요청을 보낼 때는 Content-Type: application/json을 쓰고, 모든 엔드포인트는 최대 1MB의 페이로드를 받아들여요.

출처: 문서

본문

인증과 액세스 토큰 발급

Management API를 호출하려면 먼저 Management API 액세스 토큰을 받아야 해요. 토큰을 받는 방법은 문서의 "Management API Access Tokens" 항목을 참고하면 되고, 받은 토큰은 JSON Web Token(JWT) 형태예요. 토큰의 scopes 클레임이 이 API로 어떤 요청 메서드를 실행할 수 있는지를 정해 줘요. 예를 들어 아래 토큰은 사용자에 대한 읽기 권한과 커넥션에 대한 읽기/쓰기 권한을 갖고 있어요. 허용된 스코프 밖의 요청을 시도하면 403 Forbidden 응답을 받아요.

{
  "aud" : "m8DAxghyfE0KdpzogfXgMSxrkCSdKVEF",
  "scopes" : {
    "connections" : {
      "actions" : [ "read", "update"]
    }
  },
  "iat" : "1446056652",
  "jti" : "7e9c6a991f5a227fb7ebaa522536ae4c"
}

API를 호출할 때는 액세스 토큰을 Authorization HTTP 헤더에 Bearer 인증 스킴으로 넣어 보내면 돼요. @@TENANT@@ 자리에는 실제 테넌트 도메인을 넣어 주세요.

curl -H "Authorization: Bearer ***" https://@@TENANT@@/api/v2/users

Auth0 CLI를 쓴다면 이렇게도 호출할 수 있어요.

auth0 api get "users"

요청 상관관계 ID (Request Correlation)

X-Correlation-ID HTTP 헤더를 보내면 특정 Management API 작업에 최대 64자 길이의 고유한 상관관계 ID(Correlation ID)를 붙일 수 있어요. 이 ID는 테넌트 로그에서 해당 작업을 추적하는 데 쓰여요. POST, PUT, PATCH, DELETE 메서드에서 지원돼요. 64자가 넘는 값을 보내면 처음 64자만 로그에 남아요.

curl -H "Authorization: Bearer ***" -H "x-correlation-id: client1_xyz" https://@@TENANT@@/api/v2/users

로그에는 다음과 같이 references 필드로 기록돼요.

{
  "references" : {
    "correlation_id" : "client1_xyz"
  }
}

페이지네이션 (Pagination)

큰 데이터셋을 여러 페이지로 나눠서 받기 위해 Auth0 Management API는 오프셋 기반과 체크포인트 기반 두 가지 페이지네이션 방식을 지원해요. 둘 다 지원하는 엔드포인트(예: GET /api/v2/clients, GET /api/v2/logs)에서는 큰 데이터셋에 더 효율적이고 안정적인 체크포인트 기반 방식을 추천해요.

오프셋 기반 페이지네이션 (Offset-Based)

대략 1,000개 이하의 작은 데이터셋에 적합한 단순한 방식이에요. page와 per_page 파라미터로 시작점과 페이지당 항목 수를 정해요. page는 0부터 시작하고 기본값은 0이며, per_page는 퍼블릭 클라우드 테넌트에서 최대 50, 프라이빗 클라우드에서 최대 100이고 기본값은 최댓값의 절반이에요. page * per_page가 전체 결과 수를 넘어가면 빈 배열을 반환해요.

curl -L "https://@@TENANT@@/api/v2/clients?per_page=10&page=2" \
  -H 'Authorization: Bearer ***' \
  -H 'Accept: application/json'

auth0 api get "clients" \
  -q "per_page=10" \
  -q "page=2"

체크포인트 기반 페이지네이션 (Checkpoint-Based)

커서(cursor) 기반이라고도 부르는 방식으로, 큰 데이터셋에 최적화되어 있어요. 서버가 응답에 next 체크포인트 ID를 포함시키고, 다음 페이지를 받으려면 이 ID를 다음 요청의 from 쿼리 파라미터에 그대로 넣어 사용해요. 이 ID는 불투명(opaque)해서 그대로 전달해야 해요. take는 페이지당 항목 수예요(오프셋의 per_page와 같은 제한). 체크포인트 ID는 발급 후 24시간 동안 유효하니, 오래 걸리는 작업이라면 페이지별 결과를 캐싱해 두는 게 좋아요. 이 방식은 앞으로(forward-only)만 진행되므로 뒤로 가거나 순서를 어긴 요청을 하면 오류가 날 수 있어요.

curl -L "https://@@TENANT@@/api/v2/clients?take=10&from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..." \
  -H 'Authorization: Bearer ***' \
  -H 'Accept: application/json'

auth0 api get "clients" \
  -q "take=10" \
  -q "from=Cg1HRUY3NEszUERFME40GgAiAQgCEj..."

핵심 엔드포인트와 관리 기능

Management API는 인증, 사용자, 애플리케이션, 테넌트 등 다양한 관리 작업을 엔드포인트로 제공해요. 대표적인 것들을 정리하면 다음과 같아요.

• 사용자 관리: GET /api/v2/users(사용자 목록 조회), POST /api/v2/users(사용자 생성), GET /api/v2/users/{id}(개별 사용자 조회) 등으로 사용자를 만들고 조회·수정·삭제할 수 있어요.
• 애플리케이션(클라이언트) 관리: GET /api/v2/clients로 등록된 애플리케이션 목록을 가져올 수 있고, 애플리케이션별 설정과 콜백 URL 등을 관리해요.
• 테넌트 관리: GET /api/v2/tenants/settings처럼 테넌트 설정을 조회·변경해 테넌트 전반을 운영해요.
• 커넥션·역할·토큰 관리: 소셜/DB 커넥션(/api/v2/connections), 역할(/api/v2/roles), 리소스 서버, 클라이언트 그랜트, 로그(/api/v2/logs), 세션 등도 같은 방식으로 관리할 수 있어요.

이 밖에도 조직(Organizations), 사용자 블록(Users by Email), 티켓, 훅, 규칙(Rules) 등 Auth0 대시보드에서 할 수 있는 대부분의 일이 API에 대응하는 엔드포인트로 제공돼요. 각 엔드포인트의 파라미터와 응답 형식은 아래 공식 문서에서 확인할 수 있어요.

더 알아보기 (Learn more)

• 공식 문서