베타 서비스 계정 엔드포인트

베타 서비스 계정 엔드포인트 (Beta Service Accounts Endpoints)

(beta) Service Accounts API입니다. 워크스페이스·조직의 서비스 계정을 만들고, 조회·삭제·수정하며, 역할을 부여하는 엔드포인트예요.

출처: 문서

본문

머신·자동화에 쓰는 서비스 계정을 관리하는 베타 API예요. 워크스페이스 관리자(workspace_admin) 역할이 필요하며, 서비스 계정 목록·상세를 보고 만들고, 역할을 부여하거나 갱신·삭제할 수 있답니다.

GET /v1/service-accounts — List Service Accounts (서비스 계정 목록)

워크스페이스 또는 조직 전체의 서비스 계정을 나열합니다. 워크스페이스로 스코프하면 그 위의 Workspace admin (workspace_admin) 역할이 필요해요. workspace를 생략하면 조직 전체를 나열하며, 대신 Organization admin (organization_admin) 역할이 필요해요.

쿼리 파라미터:

  • workspace_id#string|null
  • include_deleted#boolean
  • offset#integer (필수)
  • limit#integer (필수)

응답 필드 (200 Successful Response):

  • items#array<ServiceAccount> (필수)

curl:

curl https://api.mistral.ai/v1/service-accounts \
 -X GET \
 -H 'Authorization: Bearer ***'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.list({
    offset: 615331,
    limit: 383701,
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

응답 예시 (200):

{
  "items": [
    {
      "created_at": "2025-12-17T10:25:07.818693Z",
      "customer_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
      "deleted_at": null,
      "description": null,
      "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
      "name": "My resource",
      "organization_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
      "updated_at": "2025-12-17T10:41:03.469341Z",
      "workspace_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ]
}

POST /v1/service-accounts — Create Service Account (서비스 계정 생성)

워크스페이스에 서비스 계정을 만듭니다. Workspace admin (workspace_admin) 역할이 필요해요.

요청 본문:

  • name#string (필수) — 계정 이름.
  • workspace_id#string (필수) — 워크스페이스 ID.
  • description#string|null
  • role_ids#array<string>

응답 필드 (201 Successful Response):

  • id#string (필수), name#string (필수), created_at#date-time (필수), updated_at#date-time (필수), deleted_at#date-time|null (필수), description#string|null (필수), customer_id#string (필수), organization_id#string (필수), workspace_id#string (필수)

curl:

curl https://api.mistral.ai/v1/service-accounts \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "name": "My resource",
  "workspace_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.create({
    name: "<value>",
    workspaceId: "cf2146d0-158c-4b19-b8b1-ca0c68f41143",
  });

  console.log(result);
}

run();

응답 예시 (201):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "customer_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "deleted_at": null,
  "description": null,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "organization_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "workspace_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

GET /v1/service-accounts/assignable-roles — List Assignable Service Account Roles (부여 가능한 역할 목록)

서비스 계정에 부여할 수 있는 워크스페이스 역할을 나열합니다. Workspace admin (workspace_admin) 역할이 필요해요.

쿼리 파라미터:

  • workspace_id#string (필수)

응답 필드 (200 Successful Response):

  • items#array<AssignableServiceAccountRole> (필수)

curl:

curl https://api.mistral.ai/v1/service-accounts/assignable-roles \
 -X GET \
 -H 'Authorization: Bearer ***'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.listAssignableRoles({
    workspaceId: "e9326c4d-7aff-483b-9353-303bf1802e99",
  });

  console.log(result);
}

run();

응답 예시 (200):

{
  "items": [
    {
      "description": "My resource description.",
      "is_custom_role": false,
      "name": "My resource",
      "uuid": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ]
}

GET /v1/service-accounts/{service_account_id} — Get Service Account (서비스 계정 조회)

서비스 계정을 가져옵니다. Workspace admin (workspace_admin) 역할이 필요해요.

경로 파라미터:

  • service_account_id#string (필수)

응답 필드 (200 Successful Response): 생성 응답과 동일한 필드 목록.

curl:

curl https://api.mistral.ai/v1/service-accounts/{service_account_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.get({
    serviceAccountId: "68d1ecd2-32cb-473b-ae76-6d87e59f4cd1",
  });

  console.log(result);
}

run();

DELETE /v1/service-accounts/{service_account_id} — Delete Service Account (서비스 계정 삭제)

서비스 계정을 삭제합니다. Workspace admin (workspace_admin) 역할이 필요해요.

경로 파라미터:

  • service_account_id#string (필수)

curl:

curl https://api.mistral.ai/v1/service-accounts/{service_account_id} \
 -X DELETE \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  await mistral.beta.serviceAccounts.delete({
    serviceAccountId: "10f960e0-abaa-4060-9000-249255e07c45",
  });

}

run();

PATCH /v1/service-accounts/{service_account_id} — Update Service Account (서비스 계정 수정)

서비스 계정을 수정합니다. Workspace admin (workspace_admin) 역할이 필요해요.

경로 파라미터:

  • service_account_id#string (필수)

요청 본문:

  • description#string|null

응답 필드 (200 Successful Response): ServiceAccount 필드 목록.

curl:

curl https://api.mistral.ai/v1/service-accounts/{service_account_id} \
 -X PATCH \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.update({
    serviceAccountId: "2f4d1ce1-d8ad-4a87-b31b-308088fc2a76",
    updateServiceAccountRequest: {},
  });

  console.log(result);
}

run();

응답 예시 (200):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "customer_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "deleted_at": null,
  "description": null,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "organization_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "workspace_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

GET /v1/service-accounts/{service_account_id}/roles — List Service Account Roles (부여된 역할 목록)

서비스 계정에 부여된 워크스페이스 역할을 나열합니다. Workspace admin (workspace_admin) 역할이 필요해요.

경로 파라미터:

  • service_account_id#string (필수)

응답 필드 (200 Successful Response):

  • items#array<ServiceAccountRole> (필수)

curl:

curl https://api.mistral.ai/v1/service-accounts/{service_account_id}/roles \
 -X GET \
 -H 'Authorization: Bearer ***'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.listRoles({
    serviceAccountId: "0c629f5d-1a74-4b83-a740-14410ecdea21",
  });

  console.log(result);
}

run();

응답 예시 (200):

{
  "items": [
    {
      "role_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ]
}

PUT /v1/service-accounts/{service_account_id}/roles — Set Service Account Roles (역할 설정)

서비스 계정에 부여된 워크스페이스 역할을 교체합니다. Workspace admin (workspace_admin) 역할이 필요해요.

경로 파라미터:

  • service_account_id#string (필수)

요청 본문:

  • role_ids#array<string> — 부여할 역할 ID 목록.

응답 필드 (200 Successful Response):

  • items#array<ServiceAccountRole> (필수)

curl:

curl https://api.mistral.ai/v1/service-accounts/{service_account_id}/roles \
 -X PUT \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.serviceAccounts.setRoles({
    serviceAccountId: "d4686916-124a-42f1-966f-9248b120b13c",
    setServiceAccountRolesRequest: {},
  });

  console.log(result);
}

run();

응답 예시 (200):

{
  "items": [
    {
      "role_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
    }
  ]
}

더 알아보기 (Learn more)