Authentication¶
The Ning API uses the OAuth standard for authentication. An application developer is provisioned consumer credentials by the Network Creator. The API key management page is found via the “API Keys” link of the Tools section of the management page.
Once granted, the application can then request access to member resources by authenticating using the member’s email and password. All requests to the Ning API are required to be signed using the member’s token and the consumer’s key.
OAuth involves three parties:
- Resource Owner
- A member of a Ning Network
- Client
- An application accessing the member’s content on the Ning Network
- Server
- The Ning API endpoint that accepts the OAuth requests
Note
Tokens currently do not expire, but an access management system is being developed.
Obtaining Credentials¶
Before the application makes any requests on behalf of the member, the member must first authorize the application to access their data. To do this, the application performs a POST request to the Token resource. The resource verifies the identity of the member using basic authentication.
The POST request must include the OAuth parameters passed as form parameters. The Content-Type should be application/x-www-form-urlencoded. The signature is generated using the consumer key and consumer secret provisioned by Ning.
Example of obtaining token and consumer key using cURL from the command line:
curl -u admin@example.com \
-d 'oauth_signature_method=PLAINTEXT&oauth_consumer_key=0d716e57-5ada-4b29-a33c-2f4af1b26837&oauth_signature=f0963fa5-1259-434f-86fc-8a17d14b16ca%26' \
'https://external.ningapis.com/xn/rest/apiexample/1.0/Token?xn_pretty=true'
Once you run the command above and entered your password, the server will respond with an access token, access token secret, and your consumer key as seen below:
{
"success" : true,
"entry" : {
"author" : "cpor74jnszaj",
"oauthConsumerKey" : "0d716e57-5ada-4b29-a33c-2f4af1b26837",
"oauthToken" : "4e31acbd-baee-4b1d-b788-9232a8778e8f",
"oauthTokenSecret" : "1c5dee59-d3a0-4128-8581-488c236e6bfb"
},
"resources" : {
}
}
The oauthConsumerKey is equivalent to a username and is used to identify the application when making requests. It is the same value as the oauth_consumer_key in the authorization field.
The oauthToken is used to identify the member that the application is making requests for. It cannot be used with other consumer keys. The oauthTokenSecret is used when signing requests to verifiy that your application has the right to use the oauthToken.
Making a request¶
The HTTP “Authorization” header is used to transmit the application’s credentials (i.e. contains a valid OAuth token and consumer key combination for a request). Signing requests ensures that only valid applications are allowed to make requests to your site.
Note
If you are unable to set the Authorization header, you can use a X-Authorization header instead and it will be interpreted the same the Authorization header.
The authorization header begins with:
Authorization: OAuth
It is followed with a comma separated list of 4 key-value parameters:
- oauth_consumer_key
- The oauthConsumerKey given by Ning from the token request
- oauth_token
- The oauthToken given by Ning from the token request
- oauth_signature_method
- The name of the signature method. Currently PLAINTEXT and HMAC-SHA1 are supported
- oauth_signature
- Used to prove ownership of the consumer key and token. See the OAuth specification for information on how to compute the oauth_signature
- oauth_timestamp
- The POSIX timestamp when the request was made
- oauth_nonce
- A random string that when used with the oauth_timestamp ensures that the request has never been made before
- oauth_version
- The OAuth version used for this request, it must be 1.0
Note
The PLAINTEXT signature method requires a HTTPS connection
An authorization header using PLAINTEXT would look like:
Authorization: OAuth oauth_version="1.0",oauth_timestamp="1276205581",oauth_nonce="df0a1260cb2dcd536d16d85ae968237",oauth_consumer_key="f2eea643-c8e3-41c9-8b20-67509ce7b4db",oauth_token="eaa53ca4-b1cc-495e-9280-00293d8888d4",oauth_signature_method="PLAINTEXT",oauth_signature="d843c40c-c69b-474d-a037-ffc8da147814%26db23e36c-736a-4ceb-ad63-87d4c3b8a1a8"
Example of making a signed request in cURL from the command line:
curl -H 'Authorization: OAuth oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"' \
'https://external.ningapis.com/xn/rest/apiexample/1.0/Photo/recent?xn_pretty=true&fields=image.url,title&count=2'