catmaid_login allows you to login to a CATMAID server specified by a catmaid_connection object. If such an object is not specified, then the last successful connection in this R session is reused if possible otherwise a new connection object is created using options of the form "catmaid.\*" or "catmaid_\*" (see details).

The connection object returned by catmaid_login (or cached when Cache=TRUE, the default) can then be used for future requests to the CATMAID server by get/query/fetch functions.

catmaid_connection is a lower level function used by catmaid_login to create a connection object. End users should not need to call this directly, but it does document the arguments that can be used to specify a connection to a CATMAID server.

print.catmaid_connection provides a convenient summary of the status of a catmaid_connection.

catmaid_login(conn = NULL, ..., Cache = TRUE, Force = FALSE)

  username = NULL,
  password = NULL,
  authname = NULL,
  authpassword = NULL,
  token = NULL,
  authtype = NULL,
  config = NULL

# S3 method for catmaid_connection
print(x, ...)



An optional catmaid_connection connection object.


Additional arguments passed to catmaid_connection


Whether to cache open connections at login so that they can be reused automatically.


Whether to force a new login to the CATMAID server (default FALSE)


url of CATMAID server

username, password

Your CATMAID username and password.

authname, authpassword

The http username/password that optionally secures the CATMAID website. These are not the same as your CATMAID login details.


An API token (A modern alternative to providing your CATMAID username and password). See Token based authentication for details.


The http authentication scheme, see authenticate for details.


Additional curl config options. See config for details and the examples section below.


A catmaid_connection object to print


a catmaid_connection object that can be used to make authenticated http requests to a CATMAID server, specifically by making use of the $config field.


After successful login, the catmaid_connection object will contain a cookie field that includes a sessionid that is required for subsequent GET/POST operations. When Cache=TRUE (the default) the open connection object is cached and will be used when EITHER catmaid_login is called with enough information to indicate that the same server is desired OR (when no information about the server is passed to catmaid_login) the last opened connection will be used.

Note the difference between authname/authpassword and username/password. The former are for generic web authentication, which is sometimes used to protect a private catmaid site from being accessible to general web traffic. The latter are used to authenticate to the CATMAID web application itself - for example the username is the one that will be associated with any tracing carried out by you in CATMAID.

Token based authentication

CATMAID offers token based authentication as the strongly preferred alternative to specifying you CATMAID username and password. See for how to get an API token. You can then set the catmaid.token or catmaid_token package option, but no longer need to set the catmaid.username or catmaid_username and catmaid.password or catmaid_password options.

Note that you must NOT reveal this token e.g. by checking it into a version controlled script as it gives complete access to your CATMAID account.

Environment variables

You will very likely want to set the following environment variables in your .Renviron file (see Startup for details). This file is read by R on startup. In this way the catmaid package will automatically login to your preferred CATMAID server. Note that environment variables will also be inherited by child R sessions. This means for example that they will be available when running knitr reports, tests or R CMD Check from Rstudio.

  • catmaid.server or catmaid_server

  • catmaid.token or catmaid_token Preferred to using catmaid.username/password

  • catmaid.authname or catmaid_authname Optional username for basic http website authorisation

  • catmaid.authpassword or catmaid_authpassword Optional password for basic http website authorisation

  • catmaid.username or catmaid_username Your catmaid username (deprecated in favour of token)

  • catmaid.password or catmaid_password Your catmaid password (deprecated in favour of token)

An example .Renviron file might look like (the periods(.) in the environmental variable name can be also replaced with underscore(_) as mentioned above:


and must finish with a return at the end of the last line. See for details of obtaining an API token


Although setting environment variables is now the recommended approach, you can also set R startup options e.g. in your .Rprofile to specify default CATMAID login options including your personal access token. The startup options have the same names as the environment variables listed above, so you can place code along the lines of:

options(catmaid.server="", catmaid.authname="Calvin",catmaid.authpassword="hobbes", catmaid.token = "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b")

in your .Rprofile (see Startup for details). Note that it is important to have a final return at the end of your .Rprofile file.


# but see vfbcatmaid() convenience function

if (FALSE) {
## example explicitly specifying connection options
# using modern token based authentication
conn = catmaid_login(server="",
# ... or using the old fashioned approach specifiy username/password
conn = catmaid_login(server="",
  username="calvin", password="hobbesagain")

## examples assuming that catmaid.* environment variables/options are set
conn = catmaid_login()
conn = catmaid_login(server='')

## set additional curl options/headers
# This example will bypass an SSL certificate verification error on the
# remote host e.g. if it has expired. Don't this regularly of course!
conn = catmaid_login(config=httr::config(ssl_verifypeer=0))
# This example will allow you to change the http protocol version while connecting!
# Changing the http version is useful when encountering curl related errors 
conn = catmaid_login(config=httr::config(http_version=1))

## now do stuff with the connection like
skel=catmaid_fetch("1/10418394/0/0/compact-skeleton", conn=conn)
# you can also omit the connecttion because it will be cached and reused

## or for those who want to work at the lowest level