openapi: 3.0.3 x-stoplight: id: yawhegne2kh7c info: title: Secure Service Account description: |- Operations to manage Service accounts and keys. A service account is an identity that an application can use to make requests to other services without a user authorizing the requests. A service account is identified by a unique email address and has an Autodesk ID. A service account has one or more private keys. A private key is generated through an asymmetric cryptography algorithm; the paired public key is stored by Autodesk Identity. An application can use a service account's private key to generate a JWT token. The JWT token provides proof of implicit authentication and authorization for this service account; an application can exchange it for a three-legged access token for the service account. contact: name: Autodesk Platform Services email: aps.help@autodesk.com url: "https://aps.autodesk.com/" version: "1.0" servers: - url: "https://developer.api.autodesk.com" tags: - name: Account Management - name: Key Management - name: Exchange Token paths: /authentication/v2/service-accounts: post: tags: - Account Management summary: Create Service Account description: |- Creates a service account. Only a server-to-server application can own service accounts. An application can have up to 10 service accounts at any given time. Upon a successful response, the operation returns the service account ID and email address. operationId: create-service-account requestBody: content: application/json: schema: $ref: "#/components/schemas/create-service-account-payload" examples: CreateByOwner: value: name: test-service-account firstName: ServiceAccount lastName: ServiceAccount required: true description: "" responses: "201": description: Successful request; the service account has been created. content: application/json: schema: $ref: "#/components/schemas/service-account" examples: Created: value: serviceAccountId: EXAMPLE_SA_ID_001 email: test-service-account@EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX.adskserviceaccount.autodesk.com "400": description: The request could not be understood by the server due to malformed syntax. "401": description: The access token is invalid. It may have either expired or may not be a two-legged access token. Please verify the token and retry the request. "403": description: The provided Client ID is wrong or the number of service accounts that the application can have has reached the limit. Please verify the Client ID. If you've reached the limit, delete unused service accounts to create capacity. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account:write" x-codegen-request-body-name: body x-stoplight: id: tpzio13lzcdso get: tags: - Account Management summary: Get All Service Accounts description: Retrieves all service accounts associated with an application. operationId: get-all-service-accounts responses: "200": description: Successful request; the service accounts have been retrieved. content: application/json: schema: $ref: "#/components/schemas/service-accounts" examples: GetAll: value: serviceAccounts: - serviceAccountId: EXAMPLE_SA_ID_001 email: testserviceaccount1@EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX.adskserviceaccount.autodesk.com createdBy: EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX status: ENABLED createdAt: "2024-01-25 03:08:04.156576834 +0000 UTC" accessedAt: "2024-01-25 03:08:04.156576834 +0000 UTC" expiresAt: "2025-01-25 03:08:04.156576834 +0000 UTC" - serviceAccountId: EXAMPLE_SA_ID_002 email: testserviceaccount1@EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX.adskserviceaccount.autodesk.com createdBy: EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX status: DISABLED createdAt: "2024-01-25 03:08:04.156576834 +0000 UTC" accessedAt: "2024-01-25 03:08:04.156576834 +0000 UTC" expiresAt: "2025-01-25 03:08:04.156576834 +0000 UTC" "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "403": description: Invalid client; The client is wrong. Make sure the correct client id is used. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account:read" x-stoplight: id: xc6573tw5d56n parameters: [] "/authentication/v2/service-accounts/{serviceAccountId}": get: tags: - Account Management summary: Get Service Account description: Retrieves the details for a service account. operationId: get-service-account parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string responses: "200": description: Successful request; the service account has been retrieved. content: application/json: schema: $ref: "#/components/schemas/service-account-details" examples: Get: value: serviceAccountId: test-user-id-1 email: test@EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX.adskserviceaccount.autodesk.com createdBy: EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX status: ENABLED createdAt: "2024-01-25 03:08:04.156576834 +0000 UTC" accessedAt: "2024-01-25 03:08:04.156576834 +0000 UTC" expiresAt: "2025-01-25 03:08:04.156576834 +0000 UTC" "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "404": description: Not found; The service account is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account:read" x-stoplight: id: a5b64qrnha1k0 patch: tags: - Account Management summary: Enable or Disable Service Account description: |- Enables or disables a service account. When a service account is in a disabled state, it loses its capability to manage its service account key. Assertions signed by the key will be treated as invalid. This operation allows enabling a service account that is in a deactivated state. operationId: enable-disable-service-account parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/enable-disable-service-account-payload" examples: Example: value: status: ENABLED required: true description: "" responses: "200": description: Successful request; the service account has been updated. content: application/json: schema: $ref: "#/components/schemas/service-account-details" examples: EnabledDisable: value: serviceAccountId: test-user-id-1 email: test@EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX.adskserviceaccount.autodesk.com createdBy: EXAMPLE_CLIENT_ID_32CHARXXXXXXXXXXXXXXXX status: ENABLED createdAt: "2024-01-25 03:08:04.156576834 +0000 UTC" accessedAt: "2024-01-25 03:08:04.156576834 +0000 UTC" expiresAt: "2025-01-25 03:08:04.156576834 +0000 UTC" "400": description: Invalid request; The service account is already in an enabled or disabled state. Make sure the state is actually changed. "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "404": description: Not found; The service account is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account:write" delete: tags: - Account Management summary: Delete Service Account description: |- Deletes an existing service account. When a service account is deleted, all associated keys will also be deleted. operationId: delete-service-account parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string responses: "204": description: Successful request; the service account has been deleted. "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "404": description: Not found; The service account is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account:write" parameters: [] "/authentication/v2/service-accounts/{serviceAccountId}/keys": post: tags: - Key Management summary: Create Keys description: |- Creates a service account key. A service account key is a public-private key pair, generated using RSA with a key length of 2048 bits by the Identity Authorization Service (AuthZ). The private key is returned once during its creation. AuthZ only stores the public key. A service account can have up to 3 keys at any given time. operationId: create-service-account-key parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string responses: "201": description: Successful request; the service account key has been created. content: application/json: schema: $ref: "#/components/schemas/service-account-private-key" "400": description: Invalid request; The service account is not currently in an enabled state. Make sure the service account is enabled. "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "403": description: Limit exceeded; The number of keys has exceeded the limit. Delete keys to free up space. "404": description: Not found; The service account is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account_key:write" get: tags: - Key Management summary: Get All Keys description: "Lists all keys associated with the service account. This operation will only return key metadata, not the private or public key." operationId: get-all-service-account-keys parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string responses: "200": description: Successful request; the keys have been retrieved. content: application/json: schema: $ref: "#/components/schemas/service-account-keys" examples: GetAll: value: keys: - kid: 550e8400-e29b-41d4-a716-446655440000 status: ENABLED createdAt: "2024-01-25 03:08:04.156576834 +0000 UTC" accessedAt: "2024-01-25 03:08:04.156576834 +0000 UTC" - kid: 120e8400-e29b-41d4-a716-446655440003 status: DISABLED createdAt: "2024-01-25 03:08:04.156576834 +0000 UTC" accessedAt: "2024-01-25 03:08:04.156576834 +0000 UTC" "400": description: Invalid request; The service account is not currently in an enabled state. Make sure the service account is enabled. "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "404": description: Not found; The service account is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account_key:read" parameters: [] "/authentication/v2/service-accounts/{serviceAccountId}/keys/{keyId}": patch: tags: - Key Management summary: Enable or Disable Key description: Enables or disables a service account key. operationId: enable-disable-service-account-key parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string - name: keyId in: path description: The ID of the private key required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/enable-disable-service-account-key-payload" examples: Example: value: status: ENABLED required: true description: "" responses: "204": description: Successful request; the service account key has been updated. "400": description: Invalid request; The service account is not currently in an enabled state or the key is already in an enabled or disabled state. Make sure the service account is enabled and the key state is actually changed. "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "404": description: Not found; The service account or key is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account_key:write" delete: tags: - Key Management summary: Delete key description: |- Deletes an existing key. operationId: delete-service-account-key parameters: - name: serviceAccountId in: path description: The Autodesk ID of the service account required: true schema: type: string - name: keyId in: path description: The ID of the private key required: true schema: type: string responses: "204": description: Successful request; the key has been deleted. "400": description: Invalid request; The service account is not currently in an enabled state. Make sure the service account is enabled. "401": description: "Unauthorized; The token has expired, is invalid, or is not a two-legged token. Make sure a valid two-legged token is used." "404": description: Not found; The service account or key is not found. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - 2-legged: - "application:service_account_key:write" parameters: [] /authentication/v2/token: post: tags: - Exchange Token summary: Exchanging JWT assertion for token description: |- Returns a three-legged access token for the JWT assertion you provide in the request body. See the Developer's Guide topic JWT Assertions for information on how to generate a JWT assertion for this operation. This operation is only for confidential clients. It requires Basic Authorization (client_id, client_secret). Authentication information (client_id, client_secret) can be included either in the header or the body, but not both simultaneously. operationId: exchange-jwt-assertion parameters: - name: Authorization in: header description: "Must be Basic , where is a base64 encoded string of client_id:client_secret. This parameter is required only if client_id and client_secret are not provided in the request body." required: false schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object description: The request body for exchange JWT assertion required: - grant_type - assertion properties: grant_type: $ref: "#/components/schemas/grant_type" description: 'Must be "urn:ietf:params:oauth:grant-type:jwt-bearer".' client_id: type: string description: This attribute is optional; it serves as an additional option where the client can either use the authorization header or opt to send this information in the body. client_secret: type: string description: This attribute is optional; it serves as an additional option where the client can either use the authorization header or opt to send this information in the body. assertion: type: string description: The value of the JWT assertion. scope: type: array items: $ref: "#/components/schemas/scope" description: "This is a space-delimited list of scopes. The scope in the token endpoint request body should be a subset of or the same as the scope specified in the assertion. If the scope is not present, then the returned access token will have the same scope as the assertion." examples: Example: value: grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer" assertion: eyJraWQiOiI1ZGU5OTNmNC02MmIwLTQ5NWEtYTQzYS1iOTg5NmQ2ZTk1ODIiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJKbE85VEExempmSlFPR1hwSm1xOUpISlNJMEQ0VWtRNCIsInN1YiI6Ilo3NTJDVDVNS1cyUzlON0UiLCJhdWQiOiJodHRwczovL2RldmVsb3Blci5hcGkuYXV0b2Rlc2suY29tL2F1dGhlbnRpY2F0aW9uL3YyL3Rva2VuIiwiZXhwIjoxNzEwOTA3MTAwLCJzY29wZSI6WyJ1c2VyOnJlYWQiLCJkYXRhOnJlYWQiXX0.p9RNN28G38VCczbO6JgkTRfcb079_xDcDm2i4-HUqUdSZKre6jllx1IWhmwG0cm79EhC3OjJ0_zoPfKj2sP4lrPm27iXzd6x_SfD4LKS4zAJI2IERXjU05T9zWU4bfZWk0EinBysV0stvvEtZIBHczD_uAXCB5YLvyBX-O_kXqqkigNQupG9RsmE4GOjhG7pGLL_tdDYXkN46JAw-vMyXlhsdOntuZCjDOpcD4hsIueKwaqm6aLBKUTE1Htwpk0MUYmvl7AF03XDgWjhwRnJVOk_MkdF44bjSCAmsQ5uTYbWipUJjDqUy38b4xiRRRB0_qsg_kZ-DBOAFzUtYN6ilA responses: "200": description: Successful request; access token returned. content: application/json: schema: $ref: "#/components/schemas/exchange-jwt-token" "400": description: Invalid request or invalid grant; ``grant_type`` or ``assertion`` attribute may be missing or invalid; or the service account is not in an enabled state. Make sure the attributes are correct and the service account is enabled. "401": description: Invalid credentials; The client credentials are invalid. Make sure the correct client credentials are used. "403": description: Forbidden; The request was successfully validated but lacked the required permissions. Verify your credentials and permissions before you send this request again. "500": description: An unknown server-side error occurred. Please try again later. If the problem persists, please contact support. security: - basic-authorization: [] x-stoplight: id: y6swq0s0v49xx components: schemas: create-service-account-payload: title: Create Service Account Payload x-stoplight: id: aba1854d12b73 type: object description: The request body for create service account properties: name: type: string description: "The name of the service account. This name must be between 5 and 100 characters, and can contain alphanumeric characters and dashes, and include at least one alphanumeric character." firstName: type: string description: "The first name of the service account. For display purposes only. Must meet the following conditions: Length between 5 and 100 characters, contain only alphanumeric characters, dashes, and underscores, include at least one alphanumeric character, avoid inappropriate words, exclude invalid characters such as % and /, and avoid the character pattern &#. For more information, see Naming Guidelines." lastName: type: string description: "The last name of the service account. For display purposes only. Must meet the following conditions: Length between 5 and 100 characters, contain only alphanumeric characters and dashes, include at least one alphanumeric character, avoid inappropriate words, exclude invalid characters such as % and /, and avoid the character pattern &#. For more information, see Naming Guidelines." required: - name - firstName - lastName service-accounts: title: Service Accounts description: "" type: object properties: serviceAccounts: type: array description: Contains details of a list of service accounts items: $ref: "#/components/schemas/service-account-details" service-account-details: title: Service Account Details type: object description: Contains details of a service account properties: serviceAccountId: type: string description: The Autodesk ID of the service account email: type: string description: The email address of the service account createdBy: type: string description: The client ID used to create the service account status: type: string description: The status of the service account enum: - ENABLED - DISABLED - DEACTIVATED createdAt: type: string format: date-time description: The creation time of the service account accessedAt: type: string format: date-time description: This is the most recent time an access token was generated for this service account expiresAt: type: string format: date-time description: The expiration time of the service account enable-disable-service-account-payload: title: Enable or Disable Service Account Request x-stoplight: id: r1ar35l7hi8a7 type: object description: The request body for enable or disable service account properties: status: type: string description: The status of the service account $ref: "#/components/schemas/status" required: - status status: type: string enum: - ENABLED - DISABLED enable-disable-service-account-key-payload: title: Enable or Disable Service Account key Request x-stoplight: id: uk676x88o10m1 type: object description: The request body for enable or disable service account key properties: status: type: string description: The status of the service account key $ref: "#/components/schemas/status" required: - status service-account-private-key: title: Service Account Private Key type: object description: Describes a private key properties: kid: type: string description: The ID of the private key. privateKey: type: string description: "The private key value, in PEM format." service-account-keys: title: Service Account Keys type: object description: Contains details of a list of service account keys properties: keys: type: array description: List of service account keys items: $ref: "#/components/schemas/service-account-key-details" service-account-key-details: title: Service Account Key Details description: "" type: object properties: kid: type: string description: The ID of the private key status: type: string description: The status of the key enum: - ENABLED - DISABLED createdAt: type: string format: date-time description: "The creation time of the key, in UTC format" accessedAt: type: string format: date-time description: "This is the most recent time an access token was generated for this service account key, in UTC format" grant_type: type: string description: 'Must be "urn:ietf:params:oauth:grant-type:jwt-bearer".' enum: - urn:ietf:params:oauth:grant-type:jwt-bearer service-account: title: Service Account x-stoplight: id: fc1272d6180f6 type: object description: Contains the details of a newly created service account properties: serviceAccountId: type: string description: The Autodesk ID of the service account email: type: string description: The email address of the service account. It is of the form @.adskserviceaccount.autodesk.com. exchange-jwt-token: title: Exchange JWT Token type: object description: The response for exchange JWT properties: access_token: type: string description: access token value token_type: type: string description: type of token enum: - Bearer expires_in: type: integer description: access token expiry time in seconds scope: title: Scope type: string enum: - "user:read" - "user:write" - "user-profile:read" - "viewables:read" - "data:read" - "data:read:" - "data:write" - "data:create" - "data:search" - "bucket:create" - "bucket:read" - "bucket:update" - "bucket:delete" - "code:all" - "account:read" - "account:write" - "openid" - "application:service_account:write" - "application:service_account:read" - "application:service_account_key:write" - "application:service_account_key:read" securitySchemes: basic-authorization: type: http scheme: basic x-authentication_context: application context required description: Application context required. 2-legged: type: oauth2 flows: clientCredentials: tokenUrl: "https://developer.api.autodesk.com/authentication/v2/token" scopes: "application:service_account:write": Grant write access to Service Accounts "application:service_account:read": Grant read access to Service Accounts "application:service_account_key:write": Grant write access to Service Account Keys "application:service_account_key:read": Grant read access to Service Account Keys x-authentication_context: application context required description: Application context required.