Generating API Token


Can anyone outline the process that is described in the Administration Guide > API Tokens

[quote]API Tokens
The API Token is a pseudo-user account that is useful for anyone developing an application using the
Portfolio API.
Usually, an API-based app would need to log in to the Portfolio API and get a session ID, which would need
to be renewed when itssession with Portfolio times out.
Instead, you can create an API Token which the developer can use to connect to the API, bypassing the
need for additional session management.
The API Token can be granted membership to any and all catalogs, and can be assigned different access
levelsfor different catalogs.
The permissionsthat a session using an API Token has depend on the catalogsit is a member of, and its
accesslevel in each catalog.
Connections using an API Token do not count against the number of user connections available to your
Portfolio installation.
For more information about the Portfolio API, see The Portfolio API on page 65[/quote]

I am trying to implement some basic functionality calling the REST API. I am trying to avoid the whole encryption / encoding / session thing, and it would be nice to use the method above. Can anyone provide guidance on

  1. How the api token is generated (does server admin do this like they are setting up a user?)
  2. Is the token just passed in as a query param on the GETs and as payload in the PUTS/POSTS?

Any help would be appreciated. WE are running Portfolio Web 2.0.0 (20151028-63670ff)



You are exactly right. You can generate an API Token in the admin app just like adding a user, with the following steps:

  1. Launch the admin app and navigate to the Users page
  2. Click the Add New API Token action button at the bottom of the page
  3. Enter an Account Name for the token
  4. Choose which catalogs the API Token will belong to, and what access level the API Token should have
  5. Click Create, then click the View/Edit User Details
  6. Copy the Token value and save it away, you’ll use it in all the calls to the API

The token can then be used in lieu of a session id in any subsequent calls to the REST API, and you won’t have to deal with encrypting passwords and maintaining sessions.

Please don’t hesitate to let us know if you run into any questions about usage of the REST API, or if you have any feedback on using the API.



OK. So I had the admin generate token as described. However, I still receive a 401 Unauthorized.

When I issue a GET from REST client to {HOST}/api/v1/catalog?api_key=da921ac3-ab8a-437b-99d6-2c7d2eee35e1

  "faultCode": "InvalidCredentials",
  "message": "sessionId cannot be null.; nested exception is: \n\textensis.esp.exception.InvalidCredentialsException: sessionId cannot be null."

Any help here? I thought api_key would replace need for session? is ‘api_key’ the correct query sting name?


The parameter name you want is ‘session’.

You can download the REST API docs, which will tell you the param names and other info, here:

If you haven’t used docs generated by Swagger before, you can actually send messages to your Portfolio server using them.



Hi Loren,
Thanks, but I tried that as well. When I do, I receive:

  "faultCode": "InvalidCredentials",
  "message": "session-id is invalid or expired.; nested exception is: \n\textensis.esp.exception.InvalidCredentialsException: session-id is invalid or expired."

Any other ideas? Do I need to pass in special header or anything? I have swagger docs.


Hmm. Double-check your token value, make sure you copied the whole thing?
The REST call should look something like this:
localhost:8090/api/v1/catalog/?s … e178dd3ac8


BOOM! That did the trick! When admin sent the token via IM, I thought the ‘TOKEN-’ part at the beginning was just label, not actually part of the value!

So to clarify, the api token value (e.g., “TOKEN-{…}-{…}-{…}-{…}-{…}”) should just be substituted where ever ‘session’ value appears for all methods?

Thanks for your help.


Hi Matt,

Glad you got it figured out!

That’s exactly right: use the token value for the session param everywhere. You can avoid the auth methods login, logout, and public-key.

Let us know how your work goes, we always love to hear any feedback about how folks are using the API and what their experience is like.