The Login Dialog

Parameters for GET https://api.edmodo.com/oauth/authorize

client_id String
Required
Your application’s client id
redirect_uri String
Required
Your application’s callback URL
scope String
Optional
Space-delimited API scopes to request from the user, default is “basic
response_type String
Required
code” or “token”. See below.

Your app can decide whether to open the Login Dialog as a popup window or as a redirect. A popup window is suitable for desktop websites or native apps capable of showing an embedded web view. The redirect is more appropriate for mobile websites or native apps that cannot open an embedded web view.

API scopes determine what information your app can access about a user through the API.

basic Read-only access to the current user’s profile
read_groups Read-only access to the current user’s groups and group memberships
read_connections Read-only access to the current user’s teacher connections on Edmodo
read_user_email Read-only access to the current user’s email address provided to Edmodo (teachers only)
create_messages POST access to send messages in Edmodo. See description below
library_items Send items to the teacher Library or student Backpack

Note that more scopes will be made available over time.

Getting an Access Token

After the user authorizes the app (or cancels the login), The Login Dialog will redirect to your application callback URL. The response data sent to the callback URL depends on the authentication flow, determined by the “response_type” parameter. The two available flows are “token” and “code“.

Token authentication flow

The response simply includes the API access token in the URL fragment. To use this flow, your app must use SSL for all server-client communication. Note that because the response is included in a URL fragment, the data will not get sent to your server, and must be accessed through JavaScript on the callback page.

Successful login
https://myapp.com/callback#access_token=8fb2f251560655dcaeca67adf9985f66aa9f7f1f55221de602b5958280a91a7f&token_type=bearer&expires_in=7200

Canceled login
https://myapp.com/callback#error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

Code authentication flow

The response includes a temporary “code” parameter. This code must be exchanged for an access token by making a server-to-server request with the client secret. This flow must be used by apps that do not have site-wide SSL.

Successful login
https://myapp.com/callback?code=11d987616ca8a758290a3790e2dfa30ba9b8a45a9dc6723a14585d50bb304263

The “code” parameter must be exchanged for an access token by making a second request from your app’s server:

Parameters for POST https://api.edmodo.com/oauth/token

client_id String
Required
Your application’s client id
client_secret String
Required
Your application’s client secret
redirect_uri String
Required
Your application’s callback URL
code String
Required
The “code” parameter received from the login dialog
grant_type String
Required
Should be set to “authorization_code” if exchanging your “code” with an access_token

Response format{
"access_token":
"8fb2f251560655dcaeca67adf9985f66aa9f7f1f55221de602b5958280a91a7f",
"expires_in": 7200,
"token_type": "bearer",
}

Canceled login
https://myapp.com/callback?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

Token refresh flow

When requesting the access token, the API also returns an expires_in and refresh_token parameter. expires_in is the number of seconds for which the access token is valid, from the moment it is issued. Once the access token expires, the refresh_token can be used to get a new access token without requesting further authorization from the user.
POST https://api.edmodo.com/oauth/token

client_id String
Required
Your application’s client id
client_secret String
Required
Your application’s client secret
redirect_uri String
Required
Your application’s callback URL
refresh_token String
Required
The refresh token returned from /oauth/token
grant_type String
Required
Should be set to refresh_token

Keeping Users Logged In

You may persist the access token to keep the user logged in to your app. How the token is persisted is up to you. For web apps, it is best to store the access token in the session data. For native apps (desktop or mobile), the access token can be stored in the app’s data store.

Note that access tokens expire after a certain time. To get a new access token, you can open the login dialog box again. As long as the user is still logged in to edmodo.com and has not revoked API access for your app, the login dialog will immediately redirect to your callback URL with the appropriate response data to get a fresh access token.

Logging Users Out

To log users out, clear out the persisted access token. Again, how this is done is up to you and the method you use to persist the access token.

Use the return_to parameter in your query string to redirect users after a successful log-out.
https://api.edmodo.com/logout?return_to=http://yourSite.com

Using The Edmodo API

The Edmodo API is serves JSON over HTTPS from the following URL:
https://api.edmodo.com/

An access token must be included with each API request. It can be included either as a parameter or in the Authorization header of the request.

Access token as a parameter
GET https://api.edmodo.com/groups/26?access_token=8fb2f251560655

Access token as a request header
GET https://api.edmodo.com/groups/26
Authorization: Bearer 8fb2f251560655

Rate Limiting

An app is allowed a maximum of 300 API requests per user per day. Information about the remaining number of allowed requests is included in the response headers of each request. If you exceed your rate limit, the API requests will return a 403 Forbidden status.

Example Request
GET https://api.edmodo.com/groups/26
Authorization: Bearer 8fb2f251560655

Example Response
200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299

Example Response After Exceeding Rate Limit
403 Forbidden
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0

Pagination

All API endpoints that return a collection of resources use pagination. Requests that return paginated results use the following pagination parameters:

per_page Integer
Optional
The maximum number of results per page, default depends on the requested resource.
page Integer
Optional
The page number (starting with 1), default is 1

The Link header of the response will include information about the previous page or results (rel=”previous”) and the next page of results (rel=”next”). The previous and next links will only be present if a previous or next page of results exists. The total size of the collection can be determined by looking at the X-Total-Count header.

Example RequestGET https://api.edmodo.com/groups?page=2&per_page=2
Authorization: Bearer 8fb2f251560655

Example Response HeadersLink: <https://api.edmodo.com/groups?page=1&per_page=2>; rel="previous", <https://api.edmodo.com/groups?page=3&per_page=2>; rel="next"
X-Total-Count: 104