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'

Table Of Contents

Previous topic

Introduction

Next topic

Request Overview