Authentication

The Behance API makes use of industry-standard OAuth 2.0 to give access to additional API calls beyond the standard read-only endpoints. Although the read-only endpoints can be accessed at http:// or https://, all authenticated calls must be made over SSL using https://

As the owner of an application, you can authenticate with it immediately, but in order for other users to authenticate, you must first request approval from Behance. You can read more about this in Application Modes.

When to Authenticate

You can choose to request authentication from a user if you need access to additional information (such as being able to read private projects or read from a user's activity feed) or write functionality (such as posting new works-in-progress, comments, or appreciations ). Authenticating will give you more of a "logged-in" experience by providing access to features that the user has when they are logged in to Behance. Authenticated calls only require access_token, which represents your user and must be stored securely. We will revoke OAuth permissions for application found insecurely storing access tokens.

If your application does not need to provide a logged-in experience, you can forego authentication and use the read-only endpoints. This is the logged-out experience - what you see as a user browsing Behance from a logged out state. The non-authenticated endpoints only require a client_id.

Authentication Flow: Overview

In order to receive an access_token:

  1. Direct the user's browser to the Behance authorization URL. The user will be asked if they agree to give your application access to their Behance data. If they are logged out, they will be prompted to enter their credentials. (This step happens on the behance.net domain, NOT on your application's.)
  2. Behance's authentication server (from step 1) will redirect the user back to the redirect URL you passed to the Behance authorization URL along with a code GET parameter that you will use in step 3.
  3. Using the code received in step 2, request and securely store your application's access_token.

Authentication Flow: Step-by-step


Step 1: Direct the user's browser to the authorization URL
https://www.behance.net/v2/oauth/authenticate?client_id=client_id&redirect_uri=redirect_uri&scope=pipe_delimited_scopes&state=state

All arguments are required.

The state parameter is a unique string, chosen by you, used to maintain application state between the request and the callback to your redirect URI. The state you pass in this step will be returned to you in step 2, and you should check its integrity to protect against Cross-Site Request Forgery.

The scope is a pipe-separated list of the permissions you are requesting, for example:

scope=post_as|wip_read|wip_write

You can see the list of possible scopes here.

At this point the user will be prompted to log in (if necessary) and asked to give your app access to the requested permissions.

Note also that the redirect_uri parameter must match in accordance with the chart below and must be URL-encoded when passed. You can check and modify your app's registered redirect URI in the Manage Your Apps page. For example:

Registered Redirect URI Redirect URI Passed to Authentication URL Valid
http://your-redirect-uri.com/ http://your-redirect-uri.com/
http://your-redirect-uri.com/ http://your-redirect-uri.com/?foo=bar
http://your-redirect-uri.com/?foo=bar http://your-redirect-uri.com/
http://your-redirect-uri.com/?foo=bar http://your-redirect-uri.com/?foo=bar&baz=qux
http://your-redirect-uri.com/?foo=bar http://your-redirect-uri.com/?baz=qux&foo=bar
http://your-redirect-uri.com/fofum http://your-redirect-uri.com/
http://your-redirect-uri.com/fofum http://your-redirect-uri.com/fofum?foo=bar
Step 2: Receive the redirect from Behance

Once a user successfully authenticates and authorizes your application, we will redirect the user to your redirect URI with a code parameter for use in step three.

http://your_redirect_uri?code=code

If the user does not approve your request, we will still redirect back to your redirect URI but instead of a code parameter you will receive:

http://your_redirect_uri?error=access_denied&error_reason=user_denied&error_message=The+user+has+denied+your+request
Step 3: Request an access_token

POST the code your application received in the previous step, along with a few additional parameters, to our access token endpoint.

https://www.behance.net/v2/oauth/token

The required POST parameters are:

  • client_id - your client ID
  • client_secret - your client secret
  • code - your code from step 2
  • redirect_uri - your redirect URI matching exactly as passed in step 1
  • grant_type - only currently accepts authorization_code

If the request was successful, you will receive your access_token response like so:

{
      "valid": 1,
      "access_token": "abcdefg1234567890",
      "user": {
            "id": 50001,
            "first_name": "Matias",
            "last_name": "Corea",
            "username": "MatiasCorea",
            "city": "Brooklyn",
            "state": "New York",
            "country": "United States",
            "company": "Behance",
            "occupation": "Chief Designer & Co-Founder",
            "created_on": 1182475806,
            "url": "http://www.behance.net/MatiasCorea",
            "display_name": "Matias Corea",
            "images": {
                "32": "http://behance.vo.llnwd.net/profiles/50001/32xac8d5163265f6898d0b970dbfcdf4868.png",
                "50": "http://behance.vo.llnwd.net/profiles/50001/50xac8d5163265f6898d0b970dbfcdf4868.png",
                "78": "http://behance.vo.llnwd.net/profiles/50001/78xac8d5163265f6898d0b970dbfcdf4868.png",
                "115": "http://behance.vo.llnwd.net/profiles/50001/115xac8d5163265f6898d0b970dbfcdf4868.png",
                "129": "http://behance.vo.llnwd.net/profiles/50001/129xac8d5163265f6898d0b970dbfcdf4868.png",
                "138": "http://behance.vo.llnwd.net/profiles/50001/ac8d5163265f6898d0b970dbfcdf4868.png"
            },
            "fields": [
                "Web Design",
                "Typography",
                "Interaction Design"
            ]
      }
}

Although there is no explicit expiration time on access tokens, your app must be able to handle a case in which the user has revoked permissions or the token has expired.

Possible scopes

The key... gives the application permission to...
post_as may act on your behalf to comment, follow users, view and appreciate projects
activity_read Allows access to read network activity feed
collection_read Able to read collections you have marked as private
collection_write Ability to create, manipulate and delete your collections.
wip_read Able to read works in progress marked as private
wip_write Able to post, manipulate and delete a work in progress on your behalf
project_read Read private projects
invitations_read Get user's invitations.
invitations_write Respond to user's invitations.
notifications_read Able to read Notifications
notifications_delete Able to clear Notifications
push_notification_tokens_read Able to read push notification tokens
push_notification_tokens_write Able to create, manipulate and delete push notification tokens
link_user_device_app Able to Link a User Device with an App

Application Modes

Your application begins in development mode. In this mode, only the owner of the application can be authenticated for testing purposes.

Once your development is near completion, you can request that your application be approved. Once Behance approves your application, you can put it into "production" mode, which will allow others to authenticate with your application.

There are four modes that your application can be in:

Status Description
Development Use this mode for testing. Only the application owner can authenticate with the application.
Pending Your request for OAuth approval is pending. This mode behaves the same as "Development".
Production After your request has been approved and you are confident with your integration, you have the option to put your application into "Production", which will allow any user to authenticate with your application. You must manually put your application into this mode using the menu on Manage Your Apps page.
Rejected This is a serious offense. No one (including the owner) may authenticate with the application.