Zendesk Developer Platform 위에서 구축하는 경우, 401 또는 403 오류가 발생했을 가능성이 높습니다. 이러한 상태 코드는 특히 연동 서비스 수명 주기 초기에 개발자로부터 발생하는 많은 실패한 API 요청을 나타냅니다.

두 오류 모두 액세스 제어와 관련이 있지만 서로 다른 이유로 실패하며 서로 다른 접근 방식이 필요합니다. 서로 바꾸어 사용할 수 있도록 취급하면 종종 시간을 낭비하고 반복적인 요청 실패를 초래할 수 있습니다.

배우게 될 내용

이 게시물을 마칠 때쯤이면 다음 사항을 이해하게 될 것입니다.

  • Zendesk에서 401 권한 없음 오류와 403 사용 권한 없음 오류의 차이점
  • 오류를 신속하게 진단하는 방법
  • API 토큰, OAuth 액세스 토큰 및 JWT(JSON 웹 토큰)로 올바르게 인증하는 방법
  • OAuth 범위가 권한 부여에 영향을 미치는 방식
  • 잘못된 형식의 헤더, 잘못된 하위 도메인 및 만료된 자격 증명을 진단하는 방법
  • 실용적인 예와 문제 해결 단계를 통해 자신 있게 오류를 수정하는 방법

401 오류와 403 오류의 차이점

두 상태 코드 모두 액세스 제어와 관련이 있지만 요청 프로세스의 서로 다른 단계에서 실패합니다.

401 - 권한 없음

401 응답은 Zendesk API가 요청을 인증할 수 없음을 의미합니다. Zendesk는 발신자를 식별할 수 없으므로 권한이나 비즈니스 논리를 평가하지 않습니다.

일반적인 원인은 다음과 같습니다.

  • 권한 부여 헤더가 없거나 형식이 잘못됨
  • 기본 인증에 대한 잘못된 Base64 인코딩
  • 잘못된 이메일 및 토큰 형식
  • 만료 또는 취소된 API 토큰
  • 기본 인증 헤더의 OAuth 토큰
  • 메시징에 대한 올바르지 않거나 만료된 JWT

401 오류가 발생하면 요청이 수행하려는 작업이 아닌 요청이 인증되는 방식에 집중하세요.

403 사용 권한 없음

403 응답은 Zendesk가 요청을 인증했지만 인증된 ID가 요청된 작업을 수행할 권한이 없음을 의미합니다.

전형적인 원인은 다음과 같습니다.

  • 필수 범위가 없는 OAuth 토큰
  • 상담사 전용 엔드포인트에 대한 최종 사용자 자격 증명
  • 다른 브랜드에 속한 리소스에 액세스
  • 계정 IP 허용 목록 규칙
  • 일시 중단 또는 다운그레이드된 상담사 계정

403 오류가 발생하면 인증에 성공한 것입니다. 문제는 권한 부여입니다.

빠른 진단 플로우

액세스 문제를 디버그할 때 가장 빠른 방법은 문제를 단계별로 분리하는 것입니다.

  1. curl 테스트로 시작하세요. curl 요청이 실패하면 애플리케이션 코드가 아닌 자격 증명 또는 계정 구성과 관련된 문제일 수 있습니다.
  2. 올바른 Zendesk 하위 도메인을 호출했는지 확인합니다. 자격 증명은 특정 환경에 적용되며 샌드박스와 프로덕션 토큰은 상호 교환되지 않습니다.
  3. 올바른 인증 방법을 사용했는지 확인하세요. 기본 인증, OAuth, JWT가 혼동되어 실패하는 경우가 많습니다.
  4. 인증된 사용자의 역할을 확인하세요. 많은 엔드포인트가 인증에 성공하더라도 상담사 또는 관리자 권한이 필요합니다.
  5. OAuth 사용하는 경우에는 토큰에 엔드포인트에 필요한 범위가 포함되어 있는지 확인합니다.
  6. 마지막으로 요청이 실행되는 위치를 고려하세요. API 토큰 기본 인증 또는 기타 지원되지 않는 클라이언트 측 플로우를 사용할 때 브라우저 출처 요청은 종종 교차 출처 리소스 공유(CORS) 정책으로 인해 실패합니다. 브라우저에서 API를 호출해야 하는 경우에는 CORS를 지원하는 OAuth 플로우를 사용하거나, 백엔드 서비스를 통해 요청을 라우팅하거나, ZAF 클라이언트가 있는 Zendesk 앱을 사용하세요. CORS 요청에 대한 자세한 내용은 통합 티켓 관리 API에 클라이언트 측 CORS 요청하기를 참조하세요.

올바른 인증 방법

권한이나 비즈니스 논리 확인 전에 인증이 실행됩니다. 인증에 실패하면 Zendesk에서 요청을 사용자나 연동 서비스와 연결할 수 없으며 401 오류를 리턴합니다.

Zendesk는 각각 엄격한 형식 규칙이 있는 여러 가지 인증 방법을 지원합니다.

API 토큰 인증

API 토큰은 기본 인증을 사용하며 사용자 이름에는 /token 접미어가 포함되어야 합니다.

올바른 형식은 다음과 같습니다.

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://yoursubdomain.zendesk.com/api/v2/tickets.json"

401 오류를 리턴하는 일반적인 실수는 /token 접미어를 생략하는 것입니다.

emailAddress:APITOKEN

Node.js 예:

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

OAuth 인증

장기 자격 증명이나 세분화된 권한 제어가 필요한 연동 서비스는 종종 OAuth 사용합니다. Bearer 스키마로 OAuth 액세스 토큰을 보냅니다. 다음 헤더 사용:

Authorization: Bearer ACCESS_TOKEN

curl이 포함된 요청 예:

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"

Node.js 예:

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

401 OAuth 로 권한 부여되지 않음의 일반적인 원인은 잘못된 스키마로 보낸 유효한 액세스 토큰입니다. 이 경우 Zendesk는 요청을 인증할 수 없으며 범위나 권한을 평가하기 전에 401을 리턴합니다.

OAuth 토큰은 허용되는 작업을 정의하는 범위 도 사용합니다. 토큰이 인증될 수 있지만 엔드포인트에 필요한 범위가 부족한 경우에는 여전히 403 사용 권한 없음을 리턴합니다.

예를 들어 tickets:read 인 토큰은 티켓 데이터를 가져올 수 있지만 티켓을 만들거나 업데이트할 수는 없습니다. 올바른 범위 없이 쓰기를 시도하면 항상 403 오류가 리턴됩니다.

403: You do not have access to this resource

이 경우 인증은 작동하지만 올바른 범위로 토큰을 다시 생성해야 합니다. 자세한 범위는 권한 부여 유형에 대한 OAuth 토큰을 참조하세요.

메시징에 JWT 인증을 사용하는 방법

웹 또는 모바일 앱의 Zendesk 메시징은 JWT를 사용하여 최종 사용자를 식별합니다. 백엔드는 관리 센터 의 비밀키를 사용하여 JSON 웹 토큰에 서명해야 합니다. Zendesk는 메시징 세션을 사용자와 연결하기 전에 토큰의 유효성을 검사합니다.

메시징 JWT에는 Zendesk가 사용자의 ID를 확인할 수 있도록 특정 헤더 및 클레임 값이 필요합니다.

메시징 JWT에는 최소한 다음이 포함되어야 합니다.

  • 키드 – 페이로드가 아닌 JWT 헤더에 있는 관리 센터 의 키 ID
  • external_id – 사용자의 고유 식별자
  • scope – 메시징에서 최종 사용자 인증의 경우 값 “user”

name , email 및 email_verified 와 같은 선택적 클레임은 상담사 인터페이스에서 사용자 세부 정보를 채울 수 있으며 이메일 기반 ID 일치를 Support .

Node.js JWT 생성기 예:

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
  keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

external_id 또는 scope 등의 필수 클레임이 없거나 잘못된 비밀키를 사용하여 서명한 경우에는 Zendesk에서 401 권한 없음을 리턴합니다.

JWT의 일반적인 401 원인:

  • 잘못된 환경의 JWT 비밀키(샌드박스와 프로덕션)
  • 만료된 토큰 또는 올바르지 않은 시간 기반 클레임
  • external_id 또는 scope 과 같은 필수 클레임이 없습니다.
  • 올바르지 않거나 순환된 비밀키로 서명된 토큰
  • 형식이 잘못되었거나 부적절하게 인코딩된 JWT

메시징 인증을 디버그하려면 먼저 올바른 비밀키와 필수 클레임을 확인합니다. 인증에 성공했지만 ID 동작이 잘못된 것처럼 보이면 세션 전반에서 external_id 및 모든 선택적 ID 필드에 대한 안정적이고 일관된 값을 확인하세요. 자세한 내용은 애플리케이션에서 사용자 인증하기를 참조하세요.

401 오류의 일반적인 원인

401 응답은 Zendesk가 요청을 인증할 수 없으며 발신자의 신원을 확인할 수 없음을 의미합니다.

잘못된 권한 부여 헤더, 사용 중지된 토큰 또는 환경 불일치로 인해 대부분의 401 응답이 발생합니다.

다음과 같이 기본 인증 헤더의 형식을 지정합니다.

headers: {
  'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
  'Content-Type': 'application/json'
}

예기치 않은 문자, 공백 또는 인코딩 문제로 인해 종종 오류가 발생합니다.

Zendesk REST API는 브라우저 출처 인증을 Support 하지 않습니다. 클라이언트 측 JavaScript 요청은 CORS, 세션 쿠키 누락 및 지원되지 않는 인증 플로우로 인해 실패합니다. 대신 ZAF 클라이언트가 있는 백엔드 서비스나 Zendesk 앱을 사용하세요.

403 오류의 일반적인 원인

403 응답은 Zendesk가 요청을 인증했지만 권한 규칙이 액세스를 거부함을 나타냅니다.

OAuth 범위가 부족하면 대부분의 403 응답이 발생합니다. 예를 들어 tickets:read 토큰은 티켓을 가져올 수 있지만 티켓을 만들거나 업데이트할 수는 없습니다. 쓰기 시도는 항상 403 오류를 리턴합니다.

토큰을 만든 후에는 OAuth 범위를 수정할 수 없습니다. 범위가 잘못된 경우에는 새 토큰을 생성합니다.

자주 발생하는 또 다른 실수는 상담사 전용 엔드포인트로 전화를 거는 것입니다. 최종 사용자 OAuth 토큰은 /users/me를 호출할 수 있지만 티켓, 보기 또는 티켓 필드와 같은 제한된 엔드포인트에 대해서는 403을 리턴합니다.

다른 원인으로는 취소된 토큰, IP 허용 목록 규칙, 멀티브랜드 액세스 제한 등이 있습니다. 이런 경우에는 자격 증명이 비활성 상태이거나 사용자가 액세스 기준을 충족하지 않으므로 Zendesk에서 요청을 거부합니다.

단계별 문제 해결 접근 방식

1. 격리된 상태에서 자격 증명 검증:

curl -v \
  -u "email/token:token" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"
  • 실패하는 경우: 자격 증명 또는 계정과 관련된 문제일 수 있습니다.
  • 성공하는 경우: 자격 증명이 유효합니다. 애플리케이션 논리 또는 환경에 문제가 있습니다. 2단계로 이동합니다.

2. CORS 제한 확인:

curl은 작동하지만 클라이언트 측 앱이 실패하면 CORS 제한에 도달할 가능성이 있습니다. 브라우저 개발자 콘솔을 열고 오류를 검토합니다. 액세스-제어-허용-출처 메시지와 함께 401/403이 보이면 브라우저가 Zendesk에서 처리할 수 있기 전에 요청을 차단합니다.

3. 원시 요청 헤더 검사:

  • Authorization 헤더를 로그합니다. 앱에서 보내는 정확한 문자열을 인쇄하세요. 숨겨진 공백이 없는지 확인하고 Basic 또는 Bearer와 같은 접두어를 수정하세요.
  • 환경 확인: 앱이 올바른 하위 도메인을 대상으로 하는지 확인합니다. 많은 팀이 프로덕션 자격 증명으로 샌드박스 URL을 대상으로 하며, 그 반대의 경우도 마찬가지입니다.

4. 범위 및 클레임 확인:

  • OAuth 의 경우: /api/v2/oauth/tokens/current를 호출하여 현재 범위를 나열합니다. 토큰에 리소스에 필요한 범위가 있는지 확인합니다.
  • 메시징/JWT의 경우: JWT 페이로드를 재확인합니다. 키(키 ID)가 Zendesk 구성과 일치하고 올바른 서명 비밀키를 사용했는지 확인합니다.

최종 생각

Zendesk Developer Platform에서 발생하는 대부분의 401 및 403 오류는 몇 가지 예측 가능한 잘못된 구성에서 발생합니다. 인증과 권한 부여를 분리하면 진단 속도가 빨라지고 신뢰성이 높아집니다.

조기에 자격 증명을 검증하고, 범위와 역할을 확인하며, 구조화된 진단 접근 방식에 따라 문제를 신속하게 해결하고 프로덕션에서 반복을 방지하세요.

자세한 내용은 API 토큰 액세스 , OAuth 인증 , Zendesk 앱 프레임워크 및 메시징 JWT 인증 에 대한 Zendesk 문서를 참조하세요.

번역 고지 사항: 본 문서는 콘텐츠에 대한 기본적인 이해를 제공하기 위해 자동 번역 소프트웨어를 사용하여 번역되었습니다. 정확한 번역을 제공하고자 합당한 노력을 기울였으나 Zendesk는 번역의 정확성을 보장하지 않습니다.

번역된 문서에 포함된 정보의 정확성과 관련하여 질문이 있으시면 문서의 공식 버전인 영문 버전을 참조하시기 바랍니다.

Zendesk 제공