Introduction

Application security can be incredibly complicated. For most developers, it's one of the hardest part of creating an app. How can you be sure that you are protecting your users information? By integrating IBM® Cloud App ID into your apps, you can secure resources and add authentication; even when you don't have a lot of security experience. By requiring users to sign in to your app, you can store user data such as app preferences or information from the public social profiles, and then use that data to customize each experience of your app. With this API you can start building profiles on your users.

Don't see the API endpoint that you're looking for? Check out the other APIs for Management and Authentication and authorization.

API endpoint

https://<region>.appid.cloud.ibm.com

Replace <region> with the prefix that represents the geographic area where your Key Protect service instance resides. For more informaton, see Managing App ID with the API.

Authentication

This API is protected by App ID access tokens. An access token represents authorization and enables communication to protected resources. The tokens conform to JavaScript Object Signing and Encryption (JOSE) specifications and are formatted as JSON Web Tokens. There are several ways to obtain a token. For help, check out the documentation.

Don't see the API endpoint that you're looking for? Check out the other APIs for Management and Authentication and authorization.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. Check out the following table for a general description of each error type.

HTTP error code Description Recovery
200 Success The request was successful.
400 Request error There is some type of error in the request. Be sure that it is formatted in proper JSON.
401 Invalid token The request does not contain a valid access token. Obtain a new access token.
404 Not found The requested resource couldn't be found.
408 Request timeout The connection to the server timed out. Wait a few minutes and try again.
500 Internal server error The service is currently unavailable. Please wait a few minutes and try again.

Methods

Return all attributes

GET /api/v1/attributes
Request

Custom Headers

  • An App ID access token provided in the format 'Bearer <access_token>'. For more information, see obtaining tokens.

Response

Status Code

  • A successful response returns a JSON object that contains all of the attributes. If no attributes have been set, an empty JSON object is returned.

  • Unauthorized. Obtain a valid accesss token and try the request again.

  • The request failed. Wait a few minutes and try again.

Example responses

Get an attribute

GET /api/v1/attributes/{attributeName}
Request

Custom Headers

  • An App ID access token provided in the format 'Bearer <access_token>'. For more information, see obtaining tokens.

Path Parameters

  • The name of the attribute that you want to view.

Response

Status Code

  • A JSON object that contains the requested attribute and its value.

  • Unauthorized. Obtain a valid accesss token and try the request again.

  • The attribute was not found.

Example responses

Set an attribute

PUT /api/v1/attributes/{attributeName}
Request

Custom Headers

  • An App ID access token provided in the format 'Bearer <access_token>'. For more information, see obtaining tokens.

Path Parameters

  • The name of the attribute that you want to set.

The value that you want to give the attribute. For example, if the attribute name is 'favorite-food' then the attribute value might be 'pizza'.

Response

Status Code

  • A JSON object that contains the newly created or updated attribute.

  • The attribute is created.

  • The request is not formatted correctly. Validate your JSON configuration and try the request again.

  • Unauthorized. Obtain a valid accesss token and try the request again.

Example responses

Delete an attribute

DELETE /api/v1/attributes/{attributeName}
Request

Custom Headers

  • An App ID access token provided in the format 'Bearer <access_token>'. For more information, see obtaining tokens.

Path Parameters

  • The name of the attribute that you want to delete.

Response

Status Code

  • OK

  • When empty, the attribute was found and successfully deleted.

  • Unauthorized. Obtain a valid accesss token and try the request again.

  • The attribute was not found.

Example responses