Migrating to the Service Account Credentials API

TheService Account Credentials API creates short-livedcredentials for Identity and Access Management (IAM) service accounts. You can alsouse this API to sign JSON Web Tokens (JWTs), as well as blobs of binary datathat contain other types of tokens.

TheIAM API also contains methods for signing JWTsand binary blobs. As of July 1, 2020, these methodsare deprecated in the REST API and in allclient librariesfor the IAM API. Also, if you use the Google Cloud CLI to signJWTs, you might need to add a new claim to the JWT Claims Set. You can stilluse the deprecated methods, but they don't support advanced features likeHTTPrequest batching. We encourage you to migrate to theService Account Credentials API instead.

Compared to the IAM API, the Service Account Credentials APIprovides more flexibility for the expiration time of signed JWTs. In addition,the Service Account Credentials API adds multiple new API methods to generateimpersonation tokens.

This page explains how to update your existing code to use the Service AccountCredentials API. If you have feedback on this change, you cancomplete the feedback form. You can also use the email addressiam-sign-deprecation-public@google.com to request support and provide detailedfeedback.

Before you begin

  • Enable the Service Account Credentials API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the API

Enabling audit logs

If you want to receiveaudit logs for requests to sign JWTs andblobs, you mustenable Data Access audit logs for theIAM API. Enabling Data Access audit logs for theIAM API also enables these audit logs for the Service AccountCredentials API.

There are a few notable differences between the log entries that each APIgenerates:

Differences for audit log entries
Method name

IAM API

The method name (protoPayload.methodName) is one of the following:

  • google.iam.admin.v1.SignBlob
  • google.iam.admin.v1.SignJwt

Service Account Credentials API

The method name is one of the following:

  • SignBlob
  • SignJwt
Request type

IAM API

The request type (protoPayload.request.@type) is one of the following:

  • type.googleapis.com/google.iam.admin.v1.SignBlobRequest
  • type.googleapis.com/google.iam.admin.v1.SignJwtRequest

Service Account Credentials API

The request type is one of the following:

  • type.googleapis.com/google.iam.credentials.v1.SignBlobRequest
  • type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Service name

IAM API

The service name (protoPayload.serviceName) isiam.googleapis.com.

Service Account Credentials API

The service name isiamcredentials.googleapis.com.

Data Access audit logs count toward your free monthly allotment of logging dataingestion. If you exceed this allotment, you will be charged for log ingestion.For details, seePricing for Google Cloud Observability.

Migrating code for signing JWTs

This section describes how to migrate code that signs JWTs to the ServiceAccount Credentials API.

Signing JWTs with the REST API

The following table shows the differences betweensigning a JWT with the IAM REST API andsigning a JWT with the Service Account Credentials API. Updateyour code to reflect these differences:

Differences for signing a JWT
HTTP endpoints

IAM API

The IAM API uses the following HTTP methods and endpoints:

  • POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt

    In this URL,project-id is the project ID, andsa-email is the email address for the service account.

  • POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt

    In this URL, the wildcard character- takes the place of the project ID, andsa-email is the email address for the service account.

Service Account Credentials API

Use the following HTTP method and endpoint.Do not replace the wildcard character with the project ID:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt

In this URL,sa-email is the email address for the service account.

Request body

IAM API

The request body includes apayload field. Its value is the JWT payload tosign. The payload must be a JSON object, serialized as a string, that contains aJWT Claims Set.

If you provide an expiration time (exp) claim, it must be no more than12 hours in the future. If you omittheexp claim, itis added automatically and is set to1 hour in the future.

Service Account Credentials API

The request body includes apayload field that is identical to theIAM API, except for the behavior of the expiration time(exp) claim:

  • If you provide theexp claim, it must be no more than12 hours in the future.
  • If you omit theexp claim, itis not added automatically.You mustprovide this claim if you use the signed JWT to authenticate with Google APIs,or with another API that requires theexp claim.
Response body

Both APIs use the same fields in the response body.

Signing JWTs with a client library

The client libraries for the Service Account Credentials API are separate fromthe client libraries for the IAM API.

To use the Service Account Credentials API, add its client library to yourapplication, and update your code to use the new client library:

C#

Add theService Account Credentials client library for C# to your application. Use theSignJwt() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for C#, you can remove it from your application.

Go

Add theService Account Credentials client library for Go to your application. Use theIamCredentialsClient.SignJwt() function to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Go, you can remove it from your application.

Java

Add theService Account Credentials client library for Java to your application. Use theIamCredentialsClient#signJwt() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Java, you can remove it from your application.

Node.js

Add theService Account Credentials client library for Node.js to your application. Use thesignJwt() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Node.js, you can remove it from your application.

PHP

Add theService Account Credentials client library for PHP to your application. Use thesignJwt() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for PHP, you can remove it from your application.

Python

Add theService Account Credentials client library for Python to your application. Use thesign_jwt() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theiam_credentials client library, you can remove it from your application.

Ruby

Add theService Account Credentials client library for Ruby to your application. Use thesign_service_account_jwt() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Ruby, you can remove it from your application.

Migrating code for signing binary blobs

This section describes how to migrate code that signs binary blobs to theService Account Credentials API.

Signing binary blobs with the REST API

The following table shows the differences betweensigning a binary blob with the IAM REST APIandsigning a binary blob with the Service Account Credentials API.Update your code to reflect these differences:

Differences for signing a binary blob
HTTP endpoints

IAM API

The IAM API uses the following HTTP methods and endpoints:

  • POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob

    In this URL,project-id is the project ID, andsa-email is the email address for the service account.

  • POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob

    In this URL, the wildcard character- takes the place of the project ID, andsa-email is the email address for the service account.

Service Account Credentials API

Use the following HTTP method and endpoint.Do not replace the wildcard character with the project ID:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob

In this URL,sa-email is the email address for the service account.

Request body

IAM API

The request body includes abytesToSign field. Its value is a base64-encodedstring that represents the binary blob to sign.

Service Account Credentials API

The request body includes apayload field that has the same value as thebytesToSign field in the IAM API.

Response body

IAM API

The response body contains akeyId field, which identifies the key that wasused to sign the blob, and asignature field, which contains a base64-encodedstring that represents the signature.

Service Account Credentials API

The response body contains akeyId field that is identical to thekeyIdfield in the IAM API, as well as asignedBlob field thatis identical to thesignature field in the IAM API.

Note: ThesignedBlob field contains only the signature, not the original blob.

Signing binary blobs with a client library

The client libraries for the Service Account Credentials API are separate fromthe client libraries for the IAM API.

To use the Service Account Credentials API, add its client library to yourapplication, and update your code to use the new client library:

C++

If you use the Cloud Storage C++ client library to sign blobs, either directly or as a dependency of another client library:

Upgrade to version 0.9.0 or later ofgoogle-cloud-cpp.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

C#

If you use theIAM client library for C#, either directly or as a dependency of another client library:

Add theService Account Credentials client library for C# to your application. Use theSignBlob() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for C#, you can remove it from your application.

If you use the Firebase Admin DotNet SDK, either directly or as a dependency of another client library:

Upgrade to version 1.17.1 or later offirebase-admin-dotnet.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

Go

If you use theIAM client library for Go, either directly or as a dependency of another client library:

Add theService Account Credentials client library for Go to your application. Use theIamCredentialsClient.SignBlob() function to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Go, you can remove it from your application.

If you use the Firebase Admin Go SDK, either directly or as a dependency of another client library:

Upgrade to version 4.1.0 or later offirebase-admin-go.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

Java

If you use theIAM client library for Java, either directly or as a dependency of another client library:

Add theService Account Credentials client library for Java to your application. Use theIamCredentialsClient#signBlob() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Java, you can remove it from your application.

If you use the Google Auth Library for Java, either directly or as a dependency of another client library:

Upgrade to version 0.14.0 or later ofgoogle-auth-library-java.

If you use the Firebase Admin Java SDK, either directly or as a dependency of another client library:

Upgrade to version 7.0.1 or later offirebase-admin-java.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

Node.js

If you use theIAM client library for Node.js, either directly or as a dependency of another client library:

Add theService Account Credentials client library for Node.js to your application. Use thesignBlob() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Node.js, you can remove it from your application.

If you use the Google Auth Library for Node.js, either directly or as a dependency of another client library:

Upgrade to version 6.0.0 or later ofgoogle-auth-library-nodejs.

If you use the Firebase Admin Node.js SDK, either directly or as a dependency of another client library:

Upgrade to version 8.13.0 or later offirebase-admin-node.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

PHP

If you use theIAM client library for PHP, either directly or as a dependency of another client library:

Add theService Account Credentials client library for PHP to your application. Use thesignBlob() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for PHP, you can remove it from your application.

If you use the Google Auth Library for PHP, either directly or as a dependency of another client library:

Upgrade to version 1.5.0 or later ofgoogle-auth-library-php.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

Python

If you use theIAM client library for Python, either directly or as a dependency of another client library:

Add theService Account Credentials client library for Python to your application. Use thesign_blob() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theiam_credentials client library, you can remove it from your application.

If you use the Google Auth Library for Python, either directly or as a dependency of another client library:

Upgrade to version 1.21.2 or later ofgoogle-auth-library-python.

If you use the Python client for Cloud Storage, either directly or as a dependency of another client library:

Upgrade to version 1.30.0 or later ofpython-storage.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

Ruby

If you use theIAM client library for Ruby, either directly or as a dependency of another client library:

Add theService Account Credentials client library for Ruby to your application. Use thesign_service_account_blob() method to generate a signature.

The name of the service account must use the wildcard character- to represent the project ID:

Valid: Name with wildcard character

projects/-/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

Invalid: Name with project ID

projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com

If you no longer use theIAM client library for Ruby, you can remove it from your application.

If you use another client library to sign blobs:

Contactiam-sign-deprecation-public@google.com for support.

Migrating code that uses the gcloud CLI

The Google Cloud CLI provides commands that use the IAM API tosign JWTs and binary blobs, including the following:

On or after July 1, 2021, we will update these commands touse the Service Account Credentials API. This change will not affect commands tosign blobs.

If you use the gcloud CLI to sign JWTs, you must follow these stepsbefore July 1, 2021:

  1. Check whether you include the expiration time (exp) claim in the JWT ClaimsSet.

    If you already include this claim, you do not need to make any changes. Youcan skip the remaining steps.

    If you do not include this claim, continue to the next step.

  2. Check whether you use the signed JWT to authenticate with Google APIs, orwith another API that requires theexp claim.

    If you omit this claim, the IAM API automatically sets itto 1 hour in the future. Incontrast, the Service Account Credentials API does not set this fieldautomatically.

    If you are sure that you do not need theexp claim, you do not need tomake any changes. You can skip the remaining steps.

    If you know that you need theexp claim, or if you aren't sure, continueto the next step.

  3. Update your code for creating JWTs so that it adds theexp claim to the JWTClaims Set.

    You can set theexp claim up to1 hour in the future.

Checking quotas

Quota for the Service Account Credentials API is separate from quota for theIAM API. If you have received a quota increase to sign JWTsand blobs with the IAM API, you might also need to request anincrease for the Service Account Credentials API.

Note: Most Google Cloud customers use the default quota for signing JWTsand blobs. If you use the default quota, you do not need to read this section.

To view your quota and actual usage for both APIs, and to request a quotaincrease if necessary, do the following:

  1. In the Google Cloud console, go to theQuotas page.

    Go to the Quotas page

  2. Select a project. You can click a recent project, or you can clickSelectproject to search all of your projects.

  3. In theFilter table text box above the table, enterSign requests perminute, then select the value that appears.

  4. In theFilter table text box, selectOR from the drop-down list.

  5. In theFilter table text box, enterGenerate credentials, then selectthe value that appears.

    The Google Cloud console shows your current usage for signing JWTs andblobs over the past minute; your peak usage per minute over the past 7 days;and your current quota, which appears in theLimit column.

  6. Compare the quotas for each row in the table, and ensure that your quota forthe Service Account Credentials API is higher than your 7-day peak usage of theIAM API.

  7. Optional: If your quota for the Service Account Credentials API is too low,select the checkbox for the Service Account Credentials API, then clickEditquotas. Complete the form to request a quota increase.

  8. Repeat these steps for each project where you use the IAMAPI to sign JWTs and blobs.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.