서비스 계정

서비스 계정 (Service Accounts)

특정 사용자에게 소유되지 않고, 프로덕션 프로젝트를 위해 만들어진 Virtual Key가 필요할 때 사용하세요.

서비스 계정 키를 쓰는 이유:

사용자가 삭제될 때 키가 삭제되는 것을 방지.
키에 팀 멤버 한도가 아니라 팀 한도를 적용.

서비스 계정 vs 일반 키

기능	일반 키	서비스 계정 키
`user_id`	선택	항상 `null`
`team_id`	선택	필수
적용되는 한도	사용자 + 팀 한도	팀 한도만
사용자가 삭제되면 키도 삭제되나?	예	아니요 — 유지됨
메타데이터의 `service_account_id`	설정 안 됨	설정되면 불변
`team_member_key_duration`	상속	상속하지 않음

예산 & 한도

서비스 계정 키는 예산과 레이트 리밋을 사용자별이나 키 멤버별이 아니라 팀 수준에서 적용해요.

키 자체에 max_budget, tpm_limit, rpm_limit을 설정하거나, 팀에서 상속하세요.
team_member_key_duration(팀 멤버 키가 얼마나 오래 지속되는지를 제어하는 엔터프라이즈 기능)은 서비스 계정 키에는 적용되지 않아요.

사용법

/key/service-account/generate 엔드포인트를 사용해 서비스 계정 키를 생성하세요.

    curl -L -X POST 'http://localhost:4000/key/service-account/generate' \  
    -H "Authorization: Bearer ***" \  
    -H 'Content-Type: application/json' \  
    -d '{  
        "team_id": "my-unique-team"  
    }'

`service_account_id` 필드

metadata 안에 service_account_id를 선택적으로 제공해 키에 안정적이고 사람이 읽기 쉬운 식별자를 줄 수 있어요:

    curl -L -X POST 'http://localhost:4000/key/service-account/generate' \  
    -H "Authorization: Bearer ***" \  
    -H 'Content-Type: application/json' \  
    -d '{  
        "team_id": "my-unique-team",  
        "metadata": {  
            "service_account_id": "my-ci-pipeline"  
        }  
    }'

불변성 규칙. service_account_id가 설정되면 변경할 수 없어요:

동작	결과
다른 값으로 덮어쓰기	`400` 에러
명시적으로 `null`로 설정	`400` 에러
`metadata: null` 전송(지우는 효과)	`400` 에러
업데이트 시 `metadata` 완전히 생략	안전 — 기존 값 보존
같은 값 재전송	허용 (no-op)

예시 — 모든 서비스 계정 요청에 `user` 파라미터 요구

1. 서비스 계정 설정

서비스 계정 키에만 적용되는 설정을 만들고 싶다면 service_account_settings를 설정하세요.

    general_settings:  
        service_account_settings:   
            enforced_params: ["user"] # this means the "user" param is enforced for all requests made through any service account keys

2. LiteLLM Proxy Admin UI에서 서비스 계정 키 생성

3. 서비스 계정 키 테스트

실패하는 호출
성공하는 호출

    curl --location 'http://localhost:4000/chat/completions' \  
        --header 'Authorization: Bearer ***' \  
        --header 'Content-Type: application/json' \  
        --data '{  
        "model": "gpt-5.6-luna",  
        "messages": [  
            {  
            "role": "user",  
            "content": "hello"  
            }  
        ]  
    }'

예상 응답

    {  
      "error": {  
        "message": "BadRequest please pass param=user in request body. This is a required param for service account",  
        "type": "bad_request_error",  
        "param": "user",  
        "code": "400"  
      }  
    }

    curl --location 'http://localhost:4000/chat/completions' \  
        --header 'Authorization: Bearer ***' \  
        --header 'Content-Type: application/json' \  
        --data '{  
        "model": "gpt-5.6-luna",  
        "messages": [  
            {  
            "role": "user",  
            "content": "hello"  
            }  
        ],  
        "user": "test-user"  
    }'