Using SmartKeys
Every app user gets a unique token, called a SmartKey. The SmartKey is used to identify and authenticate that user to the application endpoint. It is also used to initiate OAuth dance with a provider, which then associates that user's auth tokens with their SmartKey and makes OAuth easy.
Get a user's SmartKey
GET https://{appname}-api.apigee.com/v1/smartkeys/me.json
Note: this resource requires basic auth
Parameters
Template Parameters
- appname, required - the name of the application that prefixes the app endpoint
See an example in the API Console:
GET https://{appname}-api.apigee.com/v1/smartkeys/me.json
Authenticating with an OAuth provider
Once you have a user's SmartKey, it's easy to gain authorization from any service provider you have configured. Assuming you've gone through the setup process to configure your app with the consumer token and secret granted to you by the service provider (e.g. Twitter), all you have to do is tell the OAuth API to start the authentication dance by directing the user's browser to: https://{appname}-api.apigee.com/v1/providers/{providername}/authorize?smartkey={smartkey}
Parameters
Template Parameters
- appname, required - the name of the application that prefixes the app endpoint
- providername, required - the provider with which to begin the authentication dance
Query Parameters
- smartkey, required - identifies the user whose SmartKey will store the tokens after permission has been granted
- app_callback, required - this is the URL to which the browser will be returned at the end of the authentication flow, such as https://myapp.com/oauth_success .
Percent encoding is recommended so that characters such as an & are not misinterpreted.
Important: the browser must be directed to this URL to complete the dance.
When the user has granted permission to your app, the browser will be directed back to the application, and the appropriate tokens will be associated with the SmartKey that began the dance.
Best of all, once you've added one service, you can add them all, since the OAuth API makes them work the same way.
Making Authenticated Requests
Once the authentication dance is completed with a provider, all subsequent API requests can be signed with the SmartKey. They will be mediated into OAuth by the the API Gateway. https://{appname}-api.apigee.com/v1/{providername}/1/statuses/home_timeline.json?smartkey={smartkey} Note: this resource requires SmartKey auth
Parameters
Template Parameters
- appname, required - the name of the application that prefixes the app endpoint
- providername, required - the provider to which the request is intended
Query Parameters
- smartkey, required - identifies the user whose SmartKey will store the tokens after permission has been granted
See an example in the API Console:
Retrieving User Tokens
Once the OAuth dance has been completed, the user's auth token and secret have been associated with their SmartKey. It is possible to retrieve them using (though not necessary for working with the OAuth API):
GET https://{appname}-api.apigee.com/v1/smartkeys/{smartkey}/providers/{providername}.json
Parameters
Template Parameters
- appname, required - the name of the application that prefixes the app endpoint
- smartkey, required - identifies the user whose tokens are being retrieved
- providername, required - the provider who granted the auth token and secret
See an example in the API Console:
Add or Replace User Tokens
The same resource for retrieving user tokens can be used to update them manually (used mainly for importing tokens, not necessary for working with the OAuth API):
POST https://{appname}-api.apigee.com/v1/smartkeys/{smartkey}/providers/{providername}.json
Parameters
Template Parameters
- appname, required - the name of the application that prefixes the app endpoint
- smartkey, required - identifies the user whose tokens are being updated
- providername, required - the provider who granted the auth token and secret
Query Parameters
- oauthToken, required - the auth token for a user
- oauthTokenSecret, required - the auth token secret for a user
See an example in the API Console:
Deleting User Tokens
The same resource for retrieving user tokens can be used to delete them (not necessary for working with the OAuth API):
DELETE https://{appname}-api.apigee.com/v1/smartkeys/{smartkey}/providers/{providername}.json
Parameters
Template Parameters
- appname, required - the name of the application that prefixes the app endpoint
- smartkey, required - identifies the user whose tokens are being deleted
- providername, required - the provider who granted the auth token and secret
See an example in the API Console: