OAuth 2.0 Access Tokens API

download spec authorize

OAuth 2.0 Access Tokens API

Apigee Edge uses access tokens to define a user's permissions for modifying and using a specific API. When you apply OAuth 2.0 to the API, Edge checks the request for an access token. If an access token is present, and the API is within the scope of the access token, you are allowed to access the API. Prerequisites to use this API call are:

  • The API provider has created an organization.
  • You are a registered developer.
  • You have created an app.
  • You have a valid consumer key.
  • An access token has been generated.

Resource Types

URIs are relative to https://api.enterprise.apigee.com/v1, unless otherwise noted.

AccessToken

For more information, see AccessToken.
MethodEndpointDescription
get/organizations/{org_name}/oauth2/search

Gets an OAuth2 access token by end user ID, developer app ID, or both.

Notes:

Search by app ID

All OAuth2 access tokens generated by Edge include the ID of the developer app associated with the token, and you can search for tokens based on that ID using this API. To get a list of developer app IDs for a specific developer, see List developer apps.

Search by end user ID

In some cases, you may wish to search for tokens based on the ID of the user to whom the token was issued (the actual user of the client app). This ID has to be available as a flow variable when the token is generated by the OAuthV2 policy. You can pass this ID as a query parameter or in a header with the access token request, or you can retrieve it from an external identity provider, as may be the case with the password grant type.

For example, you may wish to provide a way for users to discover which third-party apps they've authorized and to revoke their own access tokens for those apps. To search for tokens by user, you must first configure the OAuthV2 policy to insert a user ID into the token when it is created. This setup is described in Enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, app id, or both.

Use start and next to navigate through multiple pages of results

When the number of access tokens returned exceeds the limit defined in the query parameters, you will have multiple "pages," or lists, of access token results to scroll through. Use the start query parameter and next response payload element to navigate through the results.

For example, let's say your first call returns the following response payload:

{
  "list" : [ "0XXX0wX4vX43lXXXX4f8e3504oXX", "0oXzhtXdXX8kXgeXv22zv7bXXdj4", 
  (...+8 more)],
  "meta" : {
    "limit" : 10,
    "next" : "3gwbXXX2thXXzX7XXdyOblXtXyXX",
    "query" : {
      "endUser" : "{enduser}"
    },
    "start" : "",
    "totalResults" : 100
  }
}

Note that the request limited the results returned per page to 10 and that the total number of results is 100. You need a way to navigate through nine more pages of results to see all 100 results.

To do this, make another call with the next value in the output above as the start query parameter. The request URL may look something like this:

https://api.enterprise.apigee.com/v1/organizations/{org-name}/oauth2/search?enduser={enduser}&start=3gwbXXX2thXXzX7XXdyOblXtXyXX&limit=10

See the response payload below:

  "list" : [ "3gwbXXX2thXXzX7XXdyOblXtXyXX", "482XXv8XfXiouXvcXq6geXXkXXXX", 
  (...+8 more)],
  "meta" : {
    "limit" : 10,
    "next" : "Xa8mXidgXXtXXXcXnX8XXeXgXX6X",
    "query" : {
      "endUser" : "{enduser}"
    },
    "start" : "3gwbXXX2thXXzX7XXdyXblXtXyXX",
    "totalResults" : 100
    
  }
}

Note that this next page of 10 results shown above starts with the access token requested by the start parameter. To see the next 10 results, make the same call, just using the next value in the output above as the start value as shown in bold below:

https://api.enterprise.apigee.com/v1/organizations/{org-name}/oauth2/search?enduser={enduser}&start=Xa8mXidgXXtXXXcXnX8XXeXgXX6X&limit=10

You can page through each set of results by repeating this pattern of calls.

Response error details

The following describes common errors and what they mean.

  • keymanagement.service.app_id_not_found: An app ID provided in the query parameters was not found.
  • parameters_missing: An end user ID provided in the query parameters was not found.
  • InvalidValueForLimitParam: The limit value provided in the query parameters exceeds the value of the oauth_max_search_limit property defined in your keymanagement.properties files for your management server and message processor.
  • UnsupportedOperationRevoke: If this feature isn't enabled, you'll get an UnsupportedOperationRevoke error.

AccessTokenAttributes

For more information, see AccessTokenAttributes.
MethodEndpointDescription
post/organizations/{org_name}/oauth2/accesstokens/{access_token}

Enables you to perform one of the following tasks:

  • Approve or revoke an OAuth 2.0 access token. Set the action query parameter to approve or revoke, respectively. Optionally, set the cascade query parameter to true to cause refresh tokens associated with the access token to be affected by the same action.
  • Update the OAuth 2.0 access token attributes. Pass the attribute details in the request body. Only attributes specified in the request body are updated. Any other existing attributes are not affected.

AccessTokenDetails

For more information, see AccessTokenDetails.
MethodEndpointDescription
get/organizations/{org_name}/oauth2/accesstokens/{access_token}

Gets details for an OAuth 2.0 access token.

NameValue

For more information, see NameValue.
MethodEndpointDescription
post/organizations/{org_name}/oauth2/accesstokens/{access_token}

Enables you to perform one of the following tasks:

  • Approve or revoke an OAuth 2.0 access token. Set the action query parameter to approve or revoke, respectively. Optionally, set the cascade query parameter to true to cause refresh tokens associated with the access token to be affected by the same action.
  • Update the OAuth 2.0 access token attributes. Pass the attribute details in the request body. Only attributes specified in the request body are updated. Any other existing attributes are not affected.