기존 App이 있는 경우 개발자 포털의 App 페이지에서 확인, 편집 또는 삭제할 수 있습니다.
X API 및 X Ads API에 액세스하려면 각 요청에 함께 전달해야 하는 인증 자격 증명, 즉 키와 토큰이 필요합니다. 이러한 자격 증명은 사용 중인 특정 엔드포인트에서 요구하는 인증 유형에 따라 형태가 달라질 수 있습니다.
다음은 App에서 생성할 수 있는 자격 증명 종류와 사용 방법입니다:
-
API Key and Secret: 쉽게 말해 App의 사용자 이름과 비밀번호에 해당합니다. OAuth 1.0a 사용자 컨텍스트가 필요한 요청을 인증하거나, 사용자 액세스 토큰 또는 앱 액세스 토큰 등의 다른 토큰을 생성할 때 사용합니다.
-
Access Token and Secret: 일반적으로 액세스 토큰은 요청을 대신 수행하는 대상 사용자를 나타냅니다. 개발자 포털에서 생성할 수 있는 토큰은 App 소유자 사용자에 해당합니다. OAuth 1.0a 사용자 컨텍스트가 필요한 요청을 인증하는 데 사용합니다. 다른 사용자를 대신해 요청하려면 해당 사용자가 권한을 부여할 수 있도록 3-legged OAuth 플로우를 사용해야 합니다.
-
Client ID and Client Secret: 이 자격 증명은 OAuth 2.0 인증으로 사용자 액세스 토큰을 발급받는 데 사용됩니다. OAuth 1.0a와 마찬가지로 사용자 액세스 토큰은 비공개 사용자 계정 정보에 접근하거나 다른 계정을 대신해 작업을 수행하는 요청을 인증하는 데 사용되며, 더 세분화된 스코프를 통해 클라이언트 애플리케이션의 사용자에 대한 접근 범위를 정밀하게 제어할 수 있습니다.
-
App only Access Token: X에서 공개적으로 제공되는 정보로 응답하는 엔드포인트에 요청할 때 사용하는 토큰입니다.
X API 요청에 필요한 키와 토큰을 생성하는 것 외에도 권한을 설정하고, App의 사용 사례나 목적을 문서화하며, 콜백 URL을 정의하고, 관리 대시보드 내에서 App 개발 환경과 관련된 기타 설정을 수정할 수 있습니다.
X Developer Platform에서 사용 사례별로 작업을 체계화하기 위해 앱과 프로젝트를 사용할 수 있습니다. 각 프로젝트에는 Free X API 플랜은 앱 1개, Basic 플랜은 최대 2개, Pro 플랜은 최대 3개의 앱을 포함할 수 있습니다.
새로운 X API v2 엔드포인트에 액세스하려면 프로젝트에 연결된 앱의 키와 토큰을 사용해야 합니다.
프로젝트를 도입하기 전에 생성된 앱이 있는 경우 해당 앱은 “Standalone Apps” 섹션에 표시됩니다. Standalone Apps는 프로젝트 구조 바깥에 있는 앱을 의미합니다. Standalone App을 프로젝트에 연결하면 v2 엔드포인트로 요청을 보낼 수 있게 됩니다.
계정과 연결된 App을 관리하려면 대시보드를 방문하세요. 자세한 내용은 개발자 포털 문서 페이지를 참고하세요. 대시보드는 개발자가 다음 작업을 빠르고 쉽게 수행할 수 있도록 합니다:
- 기존 독립 실행형 App과 해당 App ID 보기
- 새 Project, App 또는 독립 실행형 App 생성
- 사용하지 않는 Project 또는 App 삭제
- 특정 App의 설정 검토 또는 업데이트(이름, 설명, 웹사이트, 콜백 URL, permissions 등 업데이트 포함)
- API Key & Secret, App 액세스 토큰, App 소유자의 사용자 액세스 토큰 등 App별 자격 증명 재발급
기존 X 앱이 있는 경우 developer.x.com에서 X 계정으로 로그인되어 있다면 X App dashboard에서 앱을 조회하고 수정할 수 있습니다. 참고로, 과거에 developer.x.com에서 생성된 모든 앱을 관리하기 위해 새 계정을 등록할 필요는 없습니다.
새 X 앱을 만들어야 하는 경우 개발자 계정에 가입해야 합니다. 팀 계정의 구성원이라면 새 앱을 만들기 위해 관리자 역할이 할당되어 있어야 합니다.
X에서 사용자들이 봇이 자동화된 계정임을 알 수 있도록, 봇 계정에 자동화 계정 라벨을 추가할 수 있습니다. 이러한 봇은 X API를 통해 프로그래밍된 작업을 수행합니다. 봇에 자동화 계정 라벨을 추가하면 이용자와의 신뢰를 구축하고 계정의 신뢰성을 높이며, 스팸성 봇과 구분할 수 있습니다. 이를 통해 사용자는 봇과 상호작용할 때 계정의 목적을 더 잘 이해할 수 있습니다.
봇 계정에 라벨을 추가하려면 다음 단계를 따르세요:
- 계정 설정으로 이동합니다
- “Your account”을 선택합니다
- “Automation”을 선택합니다
- “Managing account”을 선택합니다
- 다음으로, 봇을 운영하는 X 계정을 선택합니다
- 로그인하려면 비밀번호를 입력합니다
- 마지막으로, 계정에 라벨이 적용되었음을 확인하는 메시지가 표시됩니다.
X App 대시보드를 사용하면 개발자가 다음 작업을 빠르고 쉽게 수행할 수 있습니다:
- 기존 App과 Projects 및 해당 App ID 보기
- 새 Project 또는 독립 실행형 App 만들기
- Project, App 또는 독립 실행형 App 삭제
- 특정 App의 설정으로 이동해 해당 App의 설정을 엽니다. 설정에서 App 세부 정보, 키와 토큰, 권한을 확인할 수 있습니다.
- App의 사용자 인증 설정을 OAuth 1.0a 또는 OAuth 2.0 중 하나로 업데이트
참고:모든 App 키와 토큰은 더 이상 개발자 포털에서 조회할 수 없으므로, 생성될 때 안전하게 보관해야 합니다. 키와 토큰은 비밀번호 관리자를 사용해 저장할 것을 권장합니다.자격 증명을 해당 App과 매칭하는 데 도움이 되도록 API 키 힌트를 표시할 수 있습니다.
앱 권한은 OAuth 1.0a 애플리케이션-사용자 인증의 접근 수준을 나타냅니다. 앱 권한은 X App 설정에서 애플리케이션별로 구성됩니다.
사용 가능한 권한 수준은 다음 세 가지입니다:
- 읽기 전용
- 읽기 및 쓰기
- 읽기, 쓰기 및 다이렉트 메시지 접근
추가로, 사용자의 이메일 주소를 열람할 수 있도록 요청하는 권한이 있으며, 위의 세 가지 수준 중 어느 것과도 결합할 수 있습니다.
권한 수준이 변경되면 해당 X 앱에 대해 이미 발급된 모든 사용자 토큰은 폐기해야 하며, 토큰이 업데이트된 권한을 반영하도록 사용자는 앱을 다시 승인해야 합니다.
모범 사례로, 애플리케이션 또는 서비스에 필요한 범위 내에서 사용자 계정 데이터에 대한 최소한의 접근만 요청하는 것을 권장합니다.
이 권한 수준은 X 리소스(예: 사용자의 트윗, 홈 타임라인, 프로필 정보)에 대한 읽기 권한을 제공합니다. 다이렉트 메시지를 읽을 수 없으며, 어떤 요소나 객체도 수정할 수 없습니다.
이 권한 수준은 X 리소스에 대한 읽기 및 쓰기 권한을 부여합니다. 읽기 권한뿐 아니라 게시물 작성, 사용자 팔로우, 사용자 프로필 정보 항목 업데이트도 허용합니다. 또한 인증된 사용자를 대신해 답글을 숨길 수 있습니다. 이 권한 수준은 다이렉트 메시지에 대한 접근(읽기, 쓰기, 삭제 포함)을 허용하지 않습니다.
이 권한 수준은 위의 모든 항목에 대한 접근을 포함하며, 사용자 대신 다이렉트 메시지를 읽고, 쓰고, 삭제할 수 있는 기능이 추가됩니다.
인증된 모든 API 요청은 HTTP 응답에 x-access-level 헤더를 포함합니다. 이 헤더의 값은 현재 사용 중인 권한 수준을 나타냅니다. 가능한 값은 read, read-write, read-write-directmessages입니다.
OAuth 1.0a 사용자 컨텍스트와 OAuth 2.0 Authorization Code with PKCE 인증 방식은 특정 로그인 플로우를 완료한 서로 다른 X 사용자를 대신해 요청을 보낼 수 있도록 개발자를 지원합니다. 현재 사용자가 애플리케이션을 승인하도록 할 수 있는 플로우는 두 가지입니다:
사용자가 이러한 플로우를 진행하는 동안 X에 성공적으로 로그인하고 개발자의 App에 권한을 부여한 뒤에는 이동할 웹페이지나 위치가 필요합니다. 이 후속 웹페이지 또는 위치를 콜백 URL이라고 합니다.
잠재적 사용자가 이러한 플로우를 진행할 수 있도록 설정할 때 개발자는 앞서 언급한 플로우를 구성하는 인증 엔드포인트에 대한 요청과 함께 콜백 URL을 전달해야 합니다. 예를 들어 OAuth 1.0a 사용자 컨텍스트를 사용하는 개발자는 GET oauth/request_token 엔드포인트로 요청을 보낼 때 callback_url 매개변수를 포함해야 합니다. 마찬가지로 OAuth 2.0 Authorization Code with PKCE를 사용하는 개발자는 GET oauth2/authorize 엔드포인트로의 요청에 redirect_uri 매개변수를 포함해야 합니다.
이러한 매개변수를 사용하는 것 외에도 개발자는 콜백 URL이 개발자 포털의 App 설정 페이지에서 확인할 수 있는 App의 콜백 URL 허용 목록에 추가되어 있는지 반드시 확인해야 합니다.
올바르게 설정되었다면 이러한 플로우의 일부로 X에 성공적으로 로그인한 후 콜백 URL로 리디렉션됩니다.
콜백 URL을 설정할 때 다음을 염두에 두세요:
쿼리 매개변수는 HTTP로 인코딩하세요
콜백 URL을 callback_url 또는 redirect_uri 매개변수의 쿼리 값으로 전달하므로, 해당 URL을 반드시 HTTP로 인코딩해야 합니다.
콜백 URL 제한
X Apps 대시보드에는 콜백 URL을 최대 10개까지 등록할 수 있습니다. 앱 대시보드에 허용 목록으로 추가한 콜백 URL과 권한 부여 플로우에 포함하는 매개변수 값은 항상 정확히 일치해야 합니다.
콜백 URL에 요청별 데이터를 포함하려면 state 매개변수를 사용해, 사용자가 리디렉션된 후 포함될 데이터를 저장할 수 있습니다. 데이터 자체를 state 매개변수에 인코딩하거나, 서버에 상태를 저장하기 위한 세션 ID로 해당 매개변수를 사용할 수 있습니다.
콜백 URL로 localhost를 사용하지 마세요
localhost 대신 로컬에서 커스텀 호스트를 사용하거나 http(s)://127.0.0.1을 사용하세요.
커스텀 프로토콜 URL
모바일 딥 링크를 활용하려면 twitter://callback/path처럼 경로와 도메인 부분이 있는 커스텀 프로토콜 URL을 사용할 수 있습니다. 다만 피해야 하는 비허용 프로토콜 목록이 있으므로, 아래 목록을 확인하세요.
비허용 프로토콜
| |
|---|
vbscript | ldap |
javascript | mailto |
vbs | mmst |
data | mmsu |
mocha | msbd |
keyword | rtsp |
livescript | mso-offdap |
ftp | snews |
file | news |
gopher | nntp |
acrobat | outlook |
callto | stssync |
daap | rlogin |
itpc | telnet |
itms | tn3270 |
firefoxurl | shell |
hcp | sip |
{
"errors": [
{
"code":415,"message":"이 클라이언트 애플리케이션에 승인되지 않은 콜백 URL입니다. 승인된 콜백 URL은 애플리케이션 설정에서 변경할 수 있습니다."
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>이 클라이언트 애플리케이션에 대해 콜백 URL이 승인되지 않았습니다. 승인된 콜백 URL은 애플리케이션 설정에서 수정할 수 있습니다</error>
<request>/oauth/request_token</request>
</hash>
{
"error": "invalid_request",
"error_description": "리디렉션 URI로 전달된 값이 인가 코드의 URI와 일치하지 않습니다."
}
