AI Agents · 강의

인증: API 키와 OAuth

에이전트 API 액세스를 위한 Bearer 토큰, API 키 헤더, OAuth2 흐름을 다룹니다.

레슨 2/413개 단계

인증: API 키와 OAuth은(는) CoddyKit의 무료 AI Agents 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 AI Agents 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. AI Agents 강의에는 총 4개의 강의가 포함되어 있습니다.

에이전트에게 인증이 중요한 이유

에이전트가 외부 API를 호출하면 서버는 요청을 보내는 사람이 누구인지 알아야 합니다. Authentication은 신원을 증명하고, authorization은 수행할 수 있는 작업을 결정합니다. 적절한 인증이 없으면 모든 요청이 401 Unauthorized를 반환하고 에이전트는 아무 작업도 할 수 없습니다.

에이전트 개발에서는 두 가지 방식이 주로 사용됩니다. API keys와 OAuth 2.0입니다.

import requests

# Without auth — will get 401
response = requests.get('https://api.openai.com/v1/models')
print(response.status_code)  # 401 Unauthorized

# With API key in header — works
headers = {'Authorization': 'Bearer sk-proj-abc123'}
response = requests.get(
    'https://api.openai.com/v1/models',
    headers=headers
)
print(response.status_code)  # 200

Authorization 헤더의 API 키

가장 일반적인 방식은 Authorization 헤더에 Bearer 토큰으로 API 키를 보내는 것입니다. "Bearer"라는 단어는 이 토큰을 가진 사람에게 권한이 있음을 나타냅니다. 서버는 키를 소지한 사람을 신뢰합니다.

OpenAI, Anthropic, GitHub 및 대부분의 최신 API에서 이 방식을 사용합니다.

import requests
import os

api_key = os.environ['OPENAI_API_KEY']

response = requests.post(
    'https://api.openai.com/v1/chat/completions',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'gpt-4o-mini',
        'messages': [{'role': 'user', 'content': 'Hello!'}]
    }
)
print(response.json()['choices'][0]['message']['content'])

사용자 지정 헤더의 API 키(X-API-Key)

일부 API, 특히 오래되었거나 내부용인 API는 Authorization: Bearer 대신 X-API-Key와 같은 사용자 지정 헤더를 사용합니다. 헤더 이름만 다를 뿐 방식은 동일합니다. 어떤 헤더 이름을 요구하는지 API 문서에서 항상 정확히 확인하십시오.

import requests
import os

api_key = os.environ['SERVICE_API_KEY']

response = requests.get(
    'https://api.someservice.com/v1/data',
    headers={
        'X-API-Key': api_key,
        'Accept': 'application/json'
    }
)

if response.status_code == 200:
    data = response.json()
    print('Got data:', data)
elif response.status_code == 401:
    print('Invalid API key — check X-API-Key header')

환경 변수에 자격 증명 저장하기

소스 코드에 API 키를 절대 직접 작성하지 마십시오. 공개 저장소에 키를 커밋하면 봇이 몇 초 안에 찾아 악용할 수 있습니다. 올바른 방식은 자격 증명을 environment variables에 저장하고 실행 시점에 os.environ으로 읽는 것입니다.

키가 없을 때는 명확한 오류 메시지와 함께 os.environ.get()을 사용하십시오.

import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123xyz789'  # simulate a set env var

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise EnvironmentError(
        'OPENAI_API_KEY environment variable not set. '
        'Run: export OPENAI_API_KEY=your-key-here'
    )

print('API key loaded from environment (never hard-code it in source)')

로컬 개발에 python-dotenv 사용하기

개발 중에는 프로젝트 루트의 .env 파일에 키를 보관하십시오. python-dotenv 라이브러리를 사용하면 키를 자동으로 불러올 수 있습니다. 커밋되지 않도록 .env를 .gitignore에 추가하십시오.

# .env file (never commit this!)
# OPENAI_API_KEY=sk-proj-abc123
# ANTHROPIC_API_KEY=sk-ant-xyz456
# GITHUB_TOKEN=ghp_abc789

# In your Python code:
from dotenv import load_dotenv
import os

load_dotenv()  # loads .env into os.environ

openai_key = os.environ['OPENAI_API_KEY']
anthropic_key = os.environ['ANTHROPIC_API_KEY']
github_token = os.environ['GITHUB_TOKEN']

print('Keys loaded successfully')

OAuth 2.0이란 무엇입니까

OAuth 2.0은 위임된 권한 부여를 위한 표준입니다. OAuth를 사용하면 에이전트에 사용자의 비밀번호를 제공하는 대신, 사용자가 제한된 scope와 시간 범위 내에서 자신을 대신해 행동하도록 에이전트에 권한을 부여할 수 있습니다. Google, GitHub, Slack, Salesforce에서 사용합니다.

핵심 개념은 다음과 같습니다. 에이전트는 권한 부여 절차 후 access token을 받고, API 호출에 해당 토큰을 사용합니다.

# OAuth flow overview:
#
# 1. Agent redirects user to:
#    https://auth.provider.com/oauth/authorize
#      ?client_id=YOUR_CLIENT_ID
#      &redirect_uri=http://localhost:8080/callback
#      &scope=read:repo%20write:issues
#      &response_type=code
#
# 2. User logs in and grants permission
# 3. Provider redirects to your callback with ?code=AUTH_CODE
# 4. Agent exchanges code for access_token
# 5. Agent uses access_token for API calls

print('OAuth flow: authorize -> code -> token -> API calls')

OAuth2 클라이언트 자격 증명 흐름

클라이언트 자격 증명 흐름은 에이전트를 위한 가장 간단한 OAuth 흐름으로, 사용자 상호작용이 필요하지 않습니다. 에이전트 자체의 클라이언트 ID와 비밀 키로 인증하여 토큰을 받습니다. 이는 기계 간 통신에 사용됩니다.

자격 증명을 토큰 엔드포인트에 POST하면 수명이 짧은 액세스 토큰을 받습니다.

import requests
import os

client_id = os.environ['OAUTH_CLIENT_ID']
client_secret = os.environ['OAUTH_CLIENT_SECRET']
token_url = 'https://auth.example.com/oauth/token'

# Request an access token
response = requests.post(token_url, data={
    'grant_type': 'client_credentials',
    'client_id': client_id,
    'client_secret': client_secret,
    'scope': 'read:data write:tasks'
})

token_data = response.json()
access_token = token_data['access_token']
expires_in = token_data['expires_in']  # seconds
print(f'Token valid for {expires_in}s')

API 호출에 OAuth 토큰 사용하기

OAuth 액세스 토큰이 있으면 API 키와 똑같이 사용하세요. Authorization: Bearer 헤더에 넣으면 됩니다. OAuth 토큰은 만료된다는 차이점이 있으므로, 호출하기 전에 에이전트가 토큰 갱신을 처리해야 합니다.

import requests
import os
import time

class OAuthClient:
    def __init__(self, client_id, client_secret, token_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_url = token_url
        self.access_token = None
        self.token_expiry = 0

    def get_token(self):
        if time.time() < self.token_expiry - 60:  # 60s buffer
            return self.access_token
        r = requests.post(self.token_url, data={
            'grant_type': 'client_credentials',
            'client_id': self.client_id,
            'client_secret': self.client_secret
        })
        data = r.json()
        self.access_token = data['access_token']
        self.token_expiry = time.time() + data['expires_in']
        return self.access_token

    def get(self, url):
        token = self.get_token()
        return requests.get(url, headers={'Authorization': f'Bearer {token}'})

구글 인증 라이브러리를 사용하는 OAuth 2.0

구글 API에서는 구글 인증 라이브러리가 OAuth의 복잡한 작업을 모두 처리해 줍니다. 토큰을 자동으로 갱신하고, JSON 파일에서 자격 증명을 읽으며, AuthorizedSession을 통해 요청에 토큰을 첨부합니다.

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession

# Load service account credentials from JSON file
credentials = service_account.Credentials.from_service_account_file(
    'service-account.json',
    scopes=[
        'https://www.googleapis.com/auth/gmail.readonly',
        'https://www.googleapis.com/auth/calendar.events'
    ]
)

# AuthorizedSession auto-refreshes tokens
session = AuthorizedSession(credentials)

response = session.get(
    'https://www.googleapis.com/gmail/v1/users/me/messages'
)
print(response.json())

API 키 보안 모범 사례

API 키 보호는 에이전트 보안에 매우 중요합니다. 다음 규칙을 따르세요.

  • 환경 변수 또는 보안 비밀 관리자(AWS Secrets Manager, HashiCorp Vault)에 키를 저장하세요
  • 키를 기록에 남기지 마세요. 출력에서는 키를 가리세요
  • 키를 정기적으로 교체하고, 유출된 키는 즉시 폐기하세요
  • 최소 권한 원칙을 사용하여 에이전트에 필요한 범위만 요청하세요
  • 제공자가 지원하는 경우 API 키에 IP 허용 목록을 설정하세요
import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-abc123xyz789'

def get_key(env_var):
    key = os.environ.get(env_var)
    if not key:
        raise EnvironmentError(f'Missing required env var: {env_var}')
    return key

def mask_key(key):
    if len(key) < 8:
        return '***'
    return key[:4] + '...' + key[-4:]

api_key = get_key('OPENAI_API_KEY')
print(f'Using key: {mask_key(api_key)}')

에이전트에서 401 권한 없음 처리하기

에이전트가 401 Unauthorized 응답을 받았을 때는 무작정 재시도해서는 안 됩니다. 그러면 요청 제한 할당량을 낭비하게 됩니다. 대신 토큰이 만료되었는지 확인하여 갱신을 시도하거나, 키 자체가 유효하지 않은지 확인하세요. 키가 유효하지 않다면 사람이 즉시 해결할 수 있도록 알려야 합니다.

import requests
import os

def call_api_with_auth_check(url, api_key):
    response = requests.get(
        url,
        headers={'Authorization': f'Bearer {api_key}'}
    )
    if response.status_code == 401:
        error = response.json().get('error', {})
        code = error.get('code', 'unknown')
        if code == 'token_expired':
            print('Token expired — refresh needed')
            # trigger token refresh flow
        else:
            raise PermissionError(
                f'API key rejected: {error.get("message", "401 Unauthorized")}'
            )
    response.raise_for_status()
    return response.json()

빠른 확인: API 키 저장

자격 증명 관리에 대한 이해도를 확인해 보세요.

인증 복습

에이전트를 위한 두 가지 주요 인증 방식을 배웠습니다.

  • API 키 — Authorization: Bearer TOKEN 또는 X-API-Key 헤더에 전달하며, 간단하고 상태를 저장하지 않습니다
  • OAuth 2.0 — 기계 간 통신을 위한 클라이언트 자격 증명 흐름이며, 토큰은 만료되므로 갱신해야 합니다
  • 키는 항상 환경 변수에 저장하고, 소스 코드에는 저장하지 마세요
  • 로컬에서는 파이썬 환경 변수 도구를 사용하고, 운영 환경에서는 환경 변수나 보안 비밀 관리자를 사용하세요
  • 401 응답을 처리할 때는 토큰이 만료되었는지 키가 유효하지 않은지 확인하세요

견고한 인증 처리는 신뢰할 수 있는 모든 에이전트의 기반입니다.

무료로 시작

AI 튜터와 함께 AI Agents을(를) 배우세요 — 무료

브라우저에서 실제 코드를 작성하고 실행하며, 24/7 AI 튜터로부터 즉각적인 도움을 받고, 웹이나 앱에서 중단한 부분부터 계속 학습하세요.

코스
60
레슨
239

자주 묻는 질문

“인증: API 키와 OAuth” 강의는 무료인가요?

네 — “인증: API 키와 OAuth” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 AI Agents 강의 전체를 잠금 해제할 수 있습니다. AI Agents 강의에는 총 4개의 강의가 포함되어 있습니다.

“인증: API 키와 OAuth”에서 뭘 배우나요?

에이전트 API 액세스를 위한 Bearer 토큰, API 키 헤더, OAuth2 흐름을 다룹니다. 브라우저에서 직접 실행하는 실습 코드로 AI Agents을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

AI Agents을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 AI Agents은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.

“인증: API 키와 OAuth” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 AI Agents 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 AI Agents 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. 에이전트 개발자를 위한 REST API 기초
  2. 인증: API 키와 OAuth
  3. API 응답 및 오류 처리
  4. 요청 제한 및 재시도 로직
← AI Agents(으)로 돌아가기