프로그래매틱 액세스 자격 증명

프로그래매틱 액세스 자격 증명 (API 키와 IAM bearer token)

watsonx.ai에서 파운데이션 모델을 코드로 쓰려면 먼저 "내가 접근 권한이 있는 사용자"임을 증명해야 해요. 이 페이지에서는 REST API와 파이썬 라이브러리에서 쓰는 인증 방식, 그리고 API 키로 베어러 토큰을 만드는 절차를 정리해요.

출처: Credentials for programmatic access (API key and IAM bearer token) - IBM watsonx.ai 공식 문서

REST API 자격 증명

대부분의 API 메서드에서는 요청에 IAM(Identity and Access Management) bearer token을 액세스 토큰으로 넣어야 해요. 이 토큰은 API 키로 생성할 수 있어요. 인증 절차는 세 단계예요.

1. API 키 만들기

  • IBM Cloud: watsonx 계정의 내비게이션 메뉴에서 Administration > Access (IAM) > (IBM Cloud IAM으로 이동) > API keys로 가서 **Create +**를 눌러요.
  • AWS: 내비게이션 메뉴에서 Administration > Access (IAM) > Personal Access Keys로 가서 **Create +**를 눌러요.

⚠️ 보안상 API 키는 생성 시점에만 복사·다운로드할 수 있어요. 반드시 저장해 두세요.

2. API 키로 IAM bearer token 생성하기

IBM Cloud에서는 다음 명령을 실행해요.

curl -X POST \
--url https://iam.cloud.ibm.com/identity/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=${APIKEY}"

AWS 상용(commercial) 계정에서는 다음과 같이 호출해요.

curl --request POST \
--url https://<region>.aws.data.ibm.com/api/rest/mcsp/apikeys/token \
--header 'Content-Type: application/json' \
--data '{
 "apikey": "${APIKEY}"
}'

GovCloud 데이터 센터의 AWS 계정이라면 다음 명령을 써요.

curl --request POST \
--url https://<host>/dai.ibmforusgov.com/api/rest/mcsp/apikeys/token \
--header 'Content-Type: application/json' \
--data '{
 "apikey": "${APIKEY}"
}'

3. 토큰을 요청에 사용하기

응답의 access_token 필드에서 IAM bearer token을 꺼내, REST 요청의 Authorization: Bearer 헤더에 넣어요.

curl -X 'POST' <Cloud service provider URL> --header "Authorization: Bearer ***"

토큰은 만료되면 직접 갱신해야 해요. 갱신할 때는 2단계부터 다시 반복하면 돼요.

파이썬 라이브러리 자격 증명

파이썬 라이브러리를 쓸 때는 API 키나 IAM bearer token 중 하나를 선택할 수 있어요.

  • 직접 만든 IAM 토큰을 라이브러리에 넘기는 방식이라면, 토큰 만료 전에 갱신 관리까지 직접 해야 해요.
  • 대신 API 키를 그대로 전달하면 라이브러리가 알아서 처리해줘요.

ModelInference에 API 키를 바로 넣는 예시예요.

from ibm_watsonx_ai.foundation_models import ModelInference
model_inference = ModelInference(
 model_id="<api-model-id>",
 credentials={
 "apikey": "<api-key>",
 "url": "<URL>"
 },
 project_id="<project-ID>"
)

APIClient를 쓰면 라이브러리가 IAM 토큰을 생성하고 갱신까지 자동으로 처리해요. 메서드마다 자격 증명을 일일이 지정할 필요도 없답니다.

from ibm_watsonx_ai import APIClient
from ibm_watsonx_ai import Credentials
credentials = Credentials(
url = "<URL>",
api_key = "<api-key>"
)
client = APIClient(credentials)

기본 프로젝트나 스페이스 ID도 미리 설정해 둘 수 있어요.

작업 자격 증명(task credentials) 만들기

모델 튜닝처럼 오래 걸리는 작업에서는 작업 자격 증명(task credential)이 필요해요. 파이썬 라이브러리에서 이렇게 만들고 관리할 수 있어요.

task_credentials_details = client.task_credentials.store()

client.task_credentials.list()

목록 응답에 포함된 asset_id가 작업 자격 증명 ID예요. ID를 알면 삭제도 가능해요.

client.task_credentials.delete(task_credentials_id)

UI에서도 작업 자격 증명을 만들거나 삭제할 수 있어요 (Managing task credentials 참고).

더 알아보기