Skip to content

How to use the ServiceAccount API / ServiceAccountServiceClient

Introduction

Aruna offers the possibility to create service accounts that can be used impersonally, e.g. by several users at the same time or by a service that communicates with Aruna via the API.

In order for a service account to be used against the API, it must be assigned a permission for a specific resource. For security reasons, a service account can only have this one permission at the same time, which can, however, be adjusted afterwards.

The service account also must create at least a personal token for communication with the API, which takes over the specific permission of the service account in the authorisation process. If the service account is also to be entrusted with the upload and download of data, S3 credentials must be requested once from each DataProxy where data is to be stored or read.

Service Account Limitations

Service accounts behave like normal user accounts with the following limitations:

  • The service account permission can only be set on Projects
  • Only one permission can be assigned at the same time
  • Tokens can only be created on the resource the current permission is associated with and its subresources
  • All service account tokens get deleted if the permission gets set to another Project
  • License and data class updates of resources are not allowed
  • Service accounts are not allowed to send requests against the following services:
    • EndpointService
    • AuthorizationService
    • UserService
    • LicenseService

Create service account

API examples of how to create a service account.

Required permissions

Service account creation requires at least ADMIN permissions on the specific resource.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Native JSON request to create a service account with ADMIN permission on a Project
curl -d '
  {
    "name": "<service-account-name>",
    "projectId": "<project-id>",
    "permissionLevel": "PERMISSION_LEVEL_ADMIN"
  }' \
    -H 'Authorization: Bearer <AUTH_TOKEN>' \
    -H 'Content-Type: application/json' \
    -X POST 'https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Create tonic/ArunaAPI request to create a service account with ADMIN permission on a Project
let request = CreateServiceAccountRequest {
    name: "<service-account-name>".to_string(),
    project_id: "<project-id>".to_string(),
    permission: PermissionLevel::Admin as i32,
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.create_service_account(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Create tonic/ArunaAPI request to create a service account with ADMIN permission on a Project
request = CreateServiceAccountRequest(
    name="<service-account-name>",
    project_id="<project-id>",
    permission=PermissionLevel.PERMISSION_LEVEL_ADMIN
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.CreateServiceAccount(request=request)

# Do something with the response
print(f'{response}')

Create service account token

API examples of how to generate a token for a service account.

Service accounts can have as many tokens as they like, but are limited to resources that are registered hierarchically under the resource for which the service account has its specific permission set.

Required permissions

Setting the permission of a service account requires at least ADMIN permissions on the previous resource and the specified resource.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# Native JSON request to create a token with READ permissions on a dataset for a service account
curl '
  {
    "permission": {
        "projectId": "",
        "collectionId": "",
        "datasetId": "<dataset-id>",
        "objectId": "",
        "permissionLevel": "PERMISSION_LEVEL_READ"
    },
    "name": "string",
    "expiresAt": "2030-01-01T08:00:00.000Z"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}/tokens

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Create tonic/ArunaAPI request to create a token with READ permissions on a dataset for a service account
let request = CreateServiceAccountTokenRequest {
    svc_account_id: "<svc-account-id>".to_string(),
    permission: Some(Permission {
        permission_level: PermissionLevel::Read as i32,
        resource_id: Some(ResourceId::DatasetId("<dataset-id>".to_string())),
    }),
    name: "<token-name">.to_string(),
    expires_at: Some(
        NaiveDate::from_ymd_opt(2030, 01, 01)
            .unwrap()
            .and_hms_opt(8, 0, 0)
            .unwrap()
            .into(),
    ),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.create_service_account_token(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# Create tonic/ArunaAPI request to create a token with READ permissions on a dataset for a service account
request = CreateServiceAccountTokenRequest(
    svc_account_id="<svc-account-id>",
    permission=Permission(
        collection_id="<collection-id>", # (1)
        permission_level=PermissionLevel.PERMISSION_LEVEL_WRITE
    )
    name="<token-name>",
    expires_at=Timestamp(seconds=int(datetime.datetime(2030, 1, 1).timestamp()))
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.CreateServiceAccountToken(request=request)

# Do something with the response
print(f'{response}')
  1. Empty fields of the request were omitted: 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    request = CreateServiceAccountRequest(
    name="<service-account-name>",
    permission=Permission(
        project_id="<project-id>",
        collection_id="",
        dataset_id="",
        object_id="",
        permission_level=PermissionLevel.PERMISSION_LEVEL_ADMIN
    )
)

Get service account token(s)

API examples of how to fetch information of one or multiple service account tokens.

Required permissions

Fetching information of service account tokens requires at least ADMIN permissions on the resource the service account has set its permission on.

1
2
3
4
# Native JSON request to fetch information of a single specific service account token
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}/tokens/{token-id}

1
2
3
4
# Native JSON request to fetch information of all service account tokens
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}/tokens

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to fetch information of a single specific service account token
let request = GetServiceAccountTokenRequest {
    svc_account_id: "<svc_account_id>".to_string(),
    token_id: "<token_id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.get_service_account_token(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to fetch information of all service account tokens
let request = GetServiceAccountTokensRequest {
    svc_account_id: svc_account_id.to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.get_service_account_tokens(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to fetch information of a single specific service account token
request = GetServiceAccountTokenRequest(
    svc_account_id="<svc-account-id>",
    token_id="<token-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.GetServiceAccountToken(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to fetch information of all service account tokens
request = GetServiceAccountTokensRequest(
    svc_account_id="<svc-account-id>",
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.GetServiceAccountTokens(request=request)

# Do something with the response
print(f'{response}')

Delete service account token(s)

API examples of how to delete one or multiple service account tokens.

Required permissions

Deletion of service account tokens requires at least ADMIN permissions on the resource the service account has set its permission on.

1
2
3
4
# Native JSON request to delete a single specific service account token
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X DELETE https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}/tokens/{token-id}

1
2
3
4
# Native JSON request to delete all service account tokens
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X DELETE https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}/tokens

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to delete a single specific service account token
let request = DeleteServiceAccountTokenRequest {
    svc_account_id: "<svc_account_id>".to_string(),
    token_id: "<token_id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.delete_service_account_token(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to delete all service account tokens
let request = DeleteServiceAccountTokensRequest {
    svc_account_id: svc_account_id.to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.delete_service_account_tokens(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to delete a single specific service account token
request = DeleteServiceAccountTokenRequest(
    svc_account_id="<svc-account-id>",
    token_id="<token-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.DeleteServiceAccountToken(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to delete all service account tokens
request = DeleteServiceAccountTokensRequest(
    svc_account_id="<svc-account-id>",
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.DeleteServiceAccountTokens(request=request)

# Do something with the response
print(f'{response}')

Add trusted endpoint to service account

API examples of how to add a data proxy to the trusted endpoints list of a service account. This registers the service account at the data proxy and enables up- and downloads.

Required permissions

Adding a trusted endpoint requires at least ADMIN permissions on the resource the service account has set its permission on.

1
2
3
4
5
6
7
8
# Native JSON request to add a trusted endpoint to the service account
curl -d '
  {
    "endpointId": "<endpoint-id>"
  }' \ 
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}/trusted_endpoints

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to add a trusted endpoint to the service account
let request = AddTrustedEndpointsSvcAccountRequest {
    svc_account_id: "<svc_account_id>".to_string(),
    endpoint_id: "<endpoint_id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.add_trusted_endpoints_svc_account(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to delete a single specific service account token
request = AddTrustedEndpointsSvcAccountRequest(
    svc_account_id="<svc-account-id>",
    endpoint_id="<endpoint-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.AddTrustedEndpointsSvcAccount(request=request)

# Do something with the response
print(f'{response}')

Get service account S3 credentials

API examples of how to get S3 credentials for a service account from a specific DataProxy.

Required permissions

Fetching S3 credentials requires at least ADMIN permissions on the resource the service account has set its permission on.

1
2
3
4
# Native JSON request to fetch S3 credentials for the Aruna server instance default DataProxy
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET https://<URL-to-Aruna-instance-API-endpoint>/v2/user/s3_credentials/{svcAccountId}/s3_credentials/{endpointId}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request fetch S3 credentials for the Aruna server instance default DataProxy
let request = GetS3CredentialsSvcAccountRequest {
    svc_account_id: "<svc-account-id>".to_string(),
    endpoint_id: "".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.get_s3_credentials_svc_account(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to fetch S3 credentials for a specific DataProxy
let request = GetS3CredentialsSvcAccountRequest {
    svc_account_id: "<svc-account-id>".to_string(),
    endpoint_id: "<endpoint-id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.get_s3_credentials_svc_account(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to fetch S3 credentials for the Aruna server instance default DataProxy
request = GetS3CredentialsSvcAccountRequest(
    svc_account_id="<svc-account-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.GetS3CredentialsSvcAccount(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to fetch S3 credentials for a specific DataProxy
request = GetS3CredentialsSvcAccountRequest(
    svc_account_id="<svc-account-id>",
    endpoint_id="<endpoint-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.GetS3CredentialsSvcAccount(request=request)

# Do something with the response
print(f'{response}')

Remove service account S3 credentials

API examples of how to remove S3 credentials from a service account.

Required permissions

Service account deletion requires at least ADMIN permissions on the resource the service account has set its permission on.

1
2
3
4
# Native JSON request to remove S3 credentials from a service account
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X PATCH https://<URL-to-Aruna-instance-API-endpoint>/v2/user/s3_credentials/{svcAccountId}/s3_credentials/{endpointId}/revoke

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to remove S3 credentials from a service account
let request = DeleteS3CredentialsSvcAccountRequest {
    svc_account_id: "<svc-account-id>".to_string(),
    endpoint_id: "<endpoint-id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.delete_s3_credentials_svc_account(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create tonic/ArunaAPI request to remove S3 credentials from a service account
request = DeleteS3CredentialsSvcAccountRequest(
    svc_account_id="<svc-account-id>"
    endpoint_id="<endpoint-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.DeleteS3CredentialsSvcAccount(request=request)

# Do something with the response
print(f'{response}')

Delete service account

API examples of how to delete a service account.

Required permissions

Service account deletion requires at least ADMIN permissions on the resource the service account has set its permission on.

1
2
3
4
# Native JSON request to delete a service account
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X DELETE https://<URL-to-Aruna-instance-API-endpoint>/v2/service_accounts/{svc-account-id}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to delete a service account
let request = DeleteServiceAccountRequest {
    svc_account_id: "<svc_account_id>".to_string()
};

// Send the request to the Aruna instance gRPC endpoint
let response = self.service_account_client.delete_service_account(request)
                                          .await
                                          .unwrap()
                                          .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to delete a service account
request = DeleteServiceAccountTokenRequest(
    svc_account_id="<svc-account-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.service_account_client.DeleteServiceAccount(request=request)

# Do something with the response
print(f'{response}')