The Meetup API supports authentication of third-party applications using the OAuth protocol. This allows your application to access a user's data and RSVP to events on behalf of the user (after they have explicitly granted permission). If you would like to set up an OAuth consumer to use for your application, you can create one here. The procedure to making requests with OAuth is as follows:

• Fetch a request token, by using the request token URL: https://api.meetup.com/oauth/request/ signed with your consumer credentials. You must include an oauth_callback parameter. Set it to URL that the user will be redirected to after authorizing the application, or oob for out-of-band authentication. The response will include a key and secret for a request token.
• Redirect the user to the authorization url:
  http://www.meetup.com/authorize/?oauth_token=request_token_key.
• After authorizing, the user is redirected to your callback url with the oauth_token and an oauth_verifier parameter that your application will need acquire an access token. For out-of-band authorization, the verifier is displayed as a "pin" for the user to enter into your application.
• Fetch an access token using the access token URL: https://api.meetup.com/oauth/access/. If the user has chosen to allow the application and a correct oauth_verifier parameter is supplied, the request will return an access token key and secret which can be used for subsequent requests.
• Make API calls as normal - but with the necessary OAuth parameters or headers added to the request. Meetup users can see a list of applications they've authorized in their account settings page, and choose to remove an application. After a user chooses to remove an application, the access token will expire and any requests made with the token will fail. The user will need to re-authorize the application in order to allow access to continue with a new token.

Signatures are used to ensure the identity of the consumer application. Currently, the Meetup implementation of OAuth supports plaintext and HMAC_SHA1 as signature methods. For the URL portion of the signature base string, use the following values:

• Request Tokens: https://api.meetup.com/oauth/request/
• Access Tokens: https://api.meetup.com/oauth/access/
• Protected Resources (API calls): http://api.meetup.com/

OAuth Authentication ¶

Endpoint: http://www.meetup.com/authenticate/?oauth_token=request_token_key

In addition to the standard OAuth 1.0a authorization flow, we support an authentication endpoint for sites that wish to use Meetup to sign in users. Under certain conditions this endpoint will immediately redirect back to the callback URL:

• The user is already logged in to Meetup, and
• The user has already authorized your application and that authorization has not been revoked, and
• The provided request token is valid

When these conditions are not satisfied the authentication endpoint behaves the same as the authorization endpoint, sending the user to the sign in or authorization page as appropriate.

API Request Signing ¶

OAuth requests must also satisfy the following requirements:

• Include a timestamp (oauth_timestamp) which must match to within a 5 minute window of the server time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
• Include a nonce (oauth_nonce) which is a unique, randomly generated number that is specific to this request.
• Include the consumer key (oauth_consumer_key) which is used to identify the application making the request.
• Include the signature method (oauth_signature_method) and signature (oauth_signature) which are cryptographically generated digests of the resource URL, the parameters, the consumer secret, and the nonce + timestamp values.

>>> import meetup_api_client
First, create a client object specifying your applications consumer key and secret.
>>> mucli = meetup_api_client.MeetupOAuth(OAUTH_CONSUMER_KEY, OAUTH_CONSUMER_SECRET)
Then, initialize a new oauth session:
>>> oauth_session = mucli.new_session()
Fetch a request token from the server. Include your callback parameter here unless out-of-band.
>>> oauth_session.fetch_request_token(YOUR_CALLBACK_URL)
oauth_token=6d6bbb78faffccb2b3900c9c728370fb&oauth_token_secret=6b632dbc6d1dba391b350d3c20df0b8a
Get the authorization URL for this token - your application must send the user
to this URL to authorize access so the process can proceed.
>>> oauth_session.get_authorize_url()
'http://www.meetup.com/authorize/?oauth_token=6d6bbb78faffccb2b3900c9c728370fb'
Fetch an access token using the verifier passed to the callback or displayed to the user.
>>> oauth_session.fetch_access_token(VERIFIER_FROM_CALLBACK)
Make Meetup API calls. Use sess=oauth_session as a keyword parameter for each request.
>>> mucli.get_members(relation="self", sess=oauth_session)

You should store access tokens (key and secret) so that they can be re-used without forcing the user to authorize a new token every time. Initialize MeetupOAuth with an access_key and access_secret if you want an API client specific to a given user, which eliminates the need to specify a sess with each API call. The app.py script included with the python-api-client implements a basic command-line driven OAuth flow with token persistence and client-user binding.

>>> memberinfo = mucli.new_session(access_key=token_db.access_key, access_secret=token_db.access_secret)

The Meetup API implements rfc6749, the superseding specification for OAuth 1, OAuth 2. This protocol requires all communication with the Meetup servers to use HTTPS. If your application does not, you will receive an error.

We provide implementations of both the server and implicit protocol flows. We provide the following endpoints for both where necessary.

• Authorization https://secure.meetup.com/oauth2/authorize
• Access Tokens https://secure.meetup.com/oauth2/access

Before you can use OAuth 2 for user authorization, you need to either register a new OAuth consumer or add a redirect_uri to your existing consumer by clicking the edit link next to you consumer's listing. The redirect_uri you register for a given client will be used to validate future oauth2 requests. Any redirect_uri parameter that starts with the registered uri will be considered valid. For instance if you register the uri http://foo.com, http://foo.com/authed will be considered valid while http://bar.foo.com will not.

OAuth 2 consumers are also valid OAuth 1.0a consumers.

Server Flow ¶

This flow is suitable for applications that are capable of securely storing consumer secrets.

1. Requesting Authorization ¶

Redirect your user to the following URL:

https://secure.meetup.com/oauth2/authorize
    ?client_id=YOUR_CONSUMER_KEY
    &response_type=code
    &redirect_uri=YOUR_CONSUMER_REDIRECT_URI

The redirect_uri used here may vary but must start with the same redirect_uri you have registered with your consumer.

Meetup will ask the user to login if they are not already logged in. If the user has previously authorized access for the provided client_id, Meetup will immediately redirect the user back to the redirect_uri with success query parameters. If the authenticated user has not previously authorized the provided client or has revoked its access, Meetup will prompt them to authorize your application. Afterwords, Meetup will redirect the user back to the provided redirect_uri along with their response.

A successful authorization will contain these query parameters:

A failed authorization will contain an optional state parameter as mentioned above as well as an error query parameter with one of the following values

2. Requesting Access Token ¶

Have your server make an HTTP application/x-www-form-urlencoded encoded POST request for an access token with the following format:

https://secure.meetup.com/oauth2/access

client_id=YOUR_CONSUMER_KEY
&client_secret=YOUR_CONSUMER_SECRET
&grant_type=authorization_code
&redirect_uri=SAME_REDIRECT_URI_USED_FOR_PREVIOUS_STEP
&code=CODE_YOU_RECEIVED_FROM_THE_AUTHORIZATION_RESPONSE

The important parameter to note is grant_type which should be set to authorization_code. The redirect_uri used in this step must be the same redirect_uri used in the previous step.

We also support the usage of query string parameters for this method.

A successful response will contain the following data in application/json format

{
  "access_token":"ACCESS_TOKEN_TO_STORE",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"TOKEN_USED_TO_REFRESH_AUTHORIZATION"
}

A failure response will contain an application/json encoded string with an error property containing one of the following values

Implicit Flow ¶

This flow is suitable for JavaScript based browser clients.

1. Requesting Authorization and Receiving Access Token ¶

Redirect the user's browser to the following URL

https://secure.meetup.com/oauth2/authorize
   ?client_id=YOUR_CONSUMER_KEY
   &response_type=token
   &redirect_uri=YOUR_CONSUMER_REDIRECT_URI

This will ask the user to log in if they are not already logged in then prompt them to authorize your application.

The response parameters listed in the server flow's success (with the exception of refresh_token) and failure access token responses will be included in the implicit authorization's client response appended as a url fragment. Because this information is encoded in a url fragment, it can only be retrieved with client-side browser scripts.

Refreshing Your Access Token ¶

Once received, an access_token is only valid for use for one hour. This is indicated in the expires_in response parameter as seconds. You can refresh the access_token at any time and without involving the user by making a token refresh request. Note, this requires client credentials which users of the implicit flow should not be storing.

1. Refreshing Token ¶

To refresh an access_token, have your server make an HTTP application/x-www-form-urlencoded encoded POST request for an access token with the following format, this time setting grant_type to refresh_token.

https://secure.meetup.com/oauth2/access

client_id=YOUR_CONSUMER_KEY
&client_secret=YOUR_CONSUMER_SECRET
&grant_type=refresh_token
&refresh_token=REFRESH_TOKEN_YOU_RECEIVED_FROM_ACCESS_RESPONSE

We also support the usage of query string parameters for this flow but the request method must be POST.

A successful response will contain the following data in application/json format

{
  "access_token":"ACCESS_TOKEN_TO_STORE",
  "token_type": "bearer",
  "expires_in":3600,
  "refresh_token":"TOKEN_USED_TO_REFRESH_AUTHORIZATION"
}

A failure response will contain an application/json encoded string with an error property containing one of the following values

Making API Requests ¶

After successfully obtaining authorization and an access token you may now make authenticated API calls using HTTPS by appending an access_token parameter with the access token value you received from Meetup or by supplying the token value in an Authorization header prefixed with bearer and a space.

curl -H "Authorization: bearer TOKEN" https://api.meetup.com/...

User Deauthorization ¶

At any time, a user may choose to revoke access to your application here. This will invalidate any access credentials your application may have been provided for that user.

If your application has registered a de-authentication URL under your consumer settings, we will post a request containing a signed request to this URL. This message is encoded using roughly the same format as Facebook documents here. Signing these messages will guarantee you that the message came from meetup.com and assert that it has not been tampered with. We will sent an HTTP POST request to your deauthorization URL with a single parameter named signed_request whose value is set to a concatenation of:

1. An Hmac256 digest of a base 64 URL-encoded JSON message, signed with your consumer's secret key
2. a single period
3. a base 64 URL-encoded JSON message

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import org.apache.commons.codec.binary.Base64
def validatedMsg(msg: String, secret: String): Option[String] = {
   object Decoded {
     def unapply(enc: String) = Some(new String(Base64.decodeBase64(enc)))
   }
   val algo = "HmacSHA256"
   def bytes(s: String) = s.getBytes("utf8")
   msg.split("[.]") match {
      case Array(sig, encoded @ Decoded(decoded)) =>
        val m = Mac.getInstance(algo)
        m.init(new SecretKeySpec(bytes(secret), algo))
        val expect = new String(Base64.encodeBase64URLSafe(m.doFinal(bytes(encoded))))
        if (sig == expect) Some(decoded)
        else None
      case _ => None
   }
}

In order to re-obtain authorization, your application will need to re-request authorization from the user.

Access tokens received from the implicit oauth2 flow will also expire, regardless of the ageless scope, when the user logs out of meetup.com.

Optimized Mobile Authorization Display ¶

In some cases, you may want to display Meetup's authorization page in a more compact way for mobile devices or a JavaScript popup window. For these cases just append the query parameter set_mobile with a value of on.

User signup ¶

Besides asking the user to log in or to authorize your application, a user may be asked to create an account if they are not already a member. If they choose to do so through they are sent an email verification link which. Once verified, if you are using the server flow, Meetup will redirect the user to your application with the user granted authorization.

If you are implementing an implicit client, you should be aware of this in your design. Typically these clients will open a popup window to display the Meetup login and authorization forms. If the user chooses to create an account through Meetup, after the verification step, the user will only be sent to meetup.com and not redirected to your app which, by that time will most likely have lost the local state need to handle in the incoming request in a new window.

Member registration as part of an OAuth flow can be helpful if the member wishing to log into your application is not a member on Meetup. It can also add complexity. Applications may opt out of registration by providing an additional parameter named suppress, who's value is set to reg. This will have the effect of suppressing a link to register for a new Meetup account if your application user is not already a member on Meetup. You should be clear in any of your application's interstitial views prior to redirecting your user to Meetup that your application requires an account on meetup.com.

Permission Scopes ¶

OAuth 2 introduces the concept of access scopes which further restrict access of a consumer to a Meetup user's data. All o-authorized clients and API keys are implicitly provided the basic scope. We offer an additional scope, messaging, which enables Members and Organizers to send messages, preferences permitting, to one another. This feature is available for both OAuth 1.0a and OAuth 2 clients but not API key-based authentication.

To request this additional scope, pass a value of one or more scope names using + space encoding in the scope request parameter to the end point for obtaining a request token in OAuth 1.0a, https://api.meetup.com/oauth/request/, and the endpoint for obtaining authorization in OAuth 2, https://secure.meetup.com/oauth2/authorize.

Below is a table of the available Meetup API scopes names an their associated permissions.

Note, when making a request you should be able to see which scopes have been enabled and are required using in the following headers

X-OAuth-Scopes: basic, messaging
X-Accepted-OAuth-Scopes: basic, messaging

You should also be able to see which scopes are required in the method documentation.

Additional OAuth 2 Notes ¶

At this time, there is a proposal for access tokens to be associated with a token_type which determines how authenticated requests provide the access_token parameter. The two which are documented are bearer and mac, both of which are still both in early draft phases of specification. In the future, the Meetup API may require either of these in place of simply appending the access_token to a request. Application developers should be aware of this and plan accordingly.

This is the easist method to get started using the API. Simply access you API Key and append it to any request. The request's authorization will be based on the owner's key.