Splunk® Enterprise

REST API Reference Manual

Download manual as PDF

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Access control

Use the Access Control endpoints to authorize and authenticate users.

auth/login
Obtain a sesssion key for accessing the REST API.


authorization/*
Create, retrieve, and delete authorization credentials for users.
Authorization credentials provide access to the REST API.


authentication/*
Create Splunk roles and define their capabilities.
Create Splunk users and modify their settings.



LDAP REST API usage details

Splunk Enterprise users can configure LDAP user authentication using the REST API. If you are using Splunk Cloud, contact Support for assistance with setting up LDAP authentication.

LDAP user authentication lets you specify configurations, user groups, and group to role mappings to manage permissions in your Splunk deployment.

You can use the LDAP REST API for the following LDAP management tasks.

  • Configure an LDAP strategy for a server in your deployment.
  • Map LDAP groups to user roles in a server to manage group permissions.
  • Enable or disable an LDAP strategy.

To learn more about using LDAP authentication, see Set up user authentication with LDAP in Securing Splunk Enterprise.

admin/LDAP-groups

https://<host>:<mPort>/services/admin/LDAP-groups

Access and update LDAP group to role mappings.

Authentication and authorization
Requires the change_authentication capability for access.


GET

Access LDAP group mappings.

Request parameters

If you are passing in a strategy name with an LDAP group name, they must be comma separated.

Name Description
strategy LDAP strategy name
LDAPgroup LDAP group name

Returned values
For each group, the following values are returned in the response.

Name Description
roles Roles mapped to this group
strategy Strategy name
type Group type
users List of users in this group


Example request and response

curl -u admin:changeme -X GET -k https://localhost:8089/services/admin/LDAP-groups/
...
  <title>LDAP-groups</title>
  <id>https://localhost:8089/services/admin/LDAP-groups</id>
  <updated>2016-11-10T13:04:02-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/admin/LDAP-groups/_acl" rel="_acl"/>
  <opensearch:totalResults>20</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>Abc123-Admin</title>
    <id>https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin</id>
    <updated>2016-11-10T13:04:02-08:00</updated>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="list"/>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="roles">
          <s:list/>
        </s:key>
        <s:key name="strategy">ActiveDirectory_New</s:key>
        <s:key name="type">static</s:key>
        <s:key name="users">
          <s:list>
            <s:item>CN=Abc123 CI,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 1 User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 2. User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
          </s:list>
        </s:key>
      </s:dict>
    </content>
  </entry>

POST

Create an LDAP group.


Request parameters
Append the group name to the LDAP-groups/ endpoint. Pass in a strategy name using comma separation. For example, this POST creates the ActiveDirectory_New strategy and specifies the Abc123 group name.

  curl -k -u admin:password -X POST
  https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New,Abc123-Admin -d roles=user
Name Description
strategy Required. LDAP strategy name
LDAPgroup Required. LDAP group name


Returned values

Name Description
roles Roles mapped to this group.
strategy Strategy name
type Group type
users List of users in this group.


Example request and response


curl -k -u admin:password -X POST https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New,Abc123-Admin -d roles=user

.
.
.
    <title>Abc123-Admin</title>
    <id>https://localhost:8089/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin</id>
    <updated>2016-11-10T13:07:28-08:00</updated>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="list"/>
    <link href="/services/admin/LDAP-groups/ActiveDirectory_New%2CAbc123-Admin" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>splunk-system-role</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="roles">
          <s:list>
            <s:item>user</s:item>
          </s:list>
        </s:key>
        <s:key name="strategy">ActiveDirectory_New</s:key>
        <s:key name="type">static</s:key>
        <s:key name="users">
          <s:list>
            <s:item>CN=Abc123 CI,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 1 User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
            <s:item>CN=Test 2. User,OU=Abc123,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:item>
          </s:list>
        </s:key>
      </s:dict>
    </content>
  </entry>
.
.
.



authentication/LDAP-auth

https://<host>:<mPort>/services/authentication/LDAP-auth

Access or create LDAP authentication strategies on a server in your deployment.

Authentication and authorization
Requires the change_auth capability for access.

GET

Access LDAP configurations strategies.

Request parameters

Name Description
strategy Name of LDAP configuration strategy

Returned values
The response lists LDAP strategy settings.

See LDAP settings in authentication.conf for strategy settings information.

Example request and response

curl -k -u admin:password https://localhost:8089/services/authentication/LDAP-auth/
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>LDAP-auth</title>
  <id>https://localhost:8089/services/authentication/LDAP-auth</id>
  <updated>2016-11-09T16:14:07-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/LDAP-auth/_new" rel="create"/>
  <link href="/services/authentication/LDAP-auth/_acl" rel="_acl"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:14:07-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">389</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST

Create an LDAP strategy.

Usage details
Use the following endpoints to enable or disable an LDAP strategy after you create it.

  • services/authentication/LDAP-auth/{LDAP_strategy_name}/enable
  • services/authentication/LDAP-auth/{LDAP_strategy_name}/disable

Request parameters
See LDAP settings in authentication.conf for required and optional settings information.

Returned values
None.

Example request and response

curl —k u admin:password -X POST https://localhost:8089/services/authentication/LDAP-auth/ -d name=my_strategy -d groupBaseDN="CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com" -d groupMemberAttribute=sn -d groupNameAttribute=sn -d host=1.1.1.1 -d realNameAttribute=sn -d userBaseDN="OU=SAML Test,DC=qa,DC=ab2008e2,DC=com" -d userNameAttribute=sn -d bindDN="CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com" -d bindDNpassword=password

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>LDAP-auth</title>
  <id>https://localhost:8089/services/authentication/LDAP-auth</id>
  <updated>2016-11-09T16:20:14-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/LDAP-auth/_new" rel="create"/>
  <link href="/services/authentication/LDAP-auth/_acl" rel="_acl"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages>
    <s:msg type="INFO">Successfully performed a bind to the LDAP server</s:msg>
    <s:msg type="WARN">Failed to find the email attribute 'mail' in a returned user entry.</s:msg>
  </s:messages>
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:20:14-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">389</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ab2008e2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
</feed>



authentication/LDAP-auth/{LDAP_strategy_name}

https://<host>:<mPort>/services/authentication/LDAP-auth/{LDAP_strategy_name}

Access, update, or delete the {LDAP_strategy_name} strategy.

Authentication and authorization
Requires the change_auth capability for access.

GET

Access an existing LDAP strategy.

Usage details
Use the following endpoints to enable or disable the {LDAP_strategy_name} strategy.

  • services/authentication/LDAP-auth/my_strategy/enable
  • services/authentication/LDAP-auth/my_strategy/disable


Request parameters
None.

Returned values
See LDAP settings in authentication.conf for strategy settings information.

Example request and response

curl —k u admin:password https://localhost:8089/services/authentication/LDAP-auth/my_strategy
.
.
.
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:14:07-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">389</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
.
.
.

POST

Update an existing LDAP strategy.

Request parameters and returned values
See LDAP settings in authentication.conf for strategy settings information.

Example request and response

curl —k u admin:password -X POST https://localhost:8089/services/authentication/LDAP-auth/my_strategy -d port=390
  <entry>
    <title>my_strategy</title>
    <id>https://localhost:8089/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy</id>
    <updated>2016-11-09T16:14:07-08:00</updated>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="list"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="edit"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy" rel="remove"/>
    <link href="/servicesNS/nobody/system/authentication/LDAP-auth/my_strategy/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="SSLEnabled">0</s:key>
        <s:key name="anonymous_referrals">1</s:key>
        <s:key name="bindDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="bindDNpassword">********</s:key>
        <s:key name="charset">utf8</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">system</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list>
                    <s:item>*</s:item>
                  </s:list>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">1</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="emailAttribute">mail</s:key>
        <s:key name="groupBaseDN">CN=Saml user2,OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="groupMappingAttribute">dn</s:key>
        <s:key name="groupMemberAttribute">sn</s:key>
        <s:key name="groupNameAttribute">sn</s:key>
        <s:key name="host">1.1.1.1</s:key>
        <s:key name="nestedGroups">0</s:key>
        <s:key name="network_timeout">20</s:key>
        <s:key name="order">1</s:key>
        <s:key name="port">390</s:key>
        <s:key name="realNameAttribute">sn</s:key>
        <s:key name="sizelimit">1000</s:key>
        <s:key name="timelimit">15</s:key>
        <s:key name="userBaseDN">OU=SAML Test,DC=qa,DC=ad2008r2,DC=com</s:key>
        <s:key name="userNameAttribute">sn</s:key>
      </s:dict>
    </content>
  </entry>
.
.
.

DELETE

Delete an existing LDAP strategy.

Request parameters
None

Returned values
None

Example request and response

curl -k -u admin:password -X DELETE https://localhost:8089/services/authentication/LDAP-auth/my_strategy
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>LDAP-auth</title>
  <id>https://ronnie:8132/services/authentication/LDAP-auth</id>
  <updated>2016-11-09T16:18:37-08:00</updated>
  <generator build="2469654e091cb630e237a02094e683ced50f2fe5" version="20161031"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/LDAP-auth/_new" rel="create"/>
  <link href="/services/authentication/LDAP-auth/_acl" rel="_acl"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>



authentication/LDAP-auth/{LDAP_strategy_name}/enable

https://<host>:<mPort>/services/authentication/LDAP-auth/{LDAP_strategy_name}/enable


GET

Enable the {LDAP_strategy_name} LDAP strategy.

Request parameters
None

Returned values
None

Example request

curl —k u admin:password https://localhost:8089/services/authentication/LDAP-auth/my_strategy/enable

authentication/LDAP-auth/{LDAP_strategy_name}/disable

https://<host>:<mPort>/services/authentication/LDAP-auth/{LDAP_strategy_name}/disable


GET

Disable the {LDAP_strategy_name} LDAP strategy.

Request parameters
None

Returned values
None

Example request

curl —k u admin:password https://localhost:8089/services/authentication/LDAP-auth/my_strategy/disable

auth/login

Provides user authentication.

Note: This endpoint is under 'auth' and not 'authentication' for backwards compatibility.

POST auth/login

Returns a session key to be used when making REST calls to splunkd.

Request

Name Type Required Default Description
password String
The password for the user specified with username.
username String
The Splunk account username.

Response Codes

Status Code Description
200 Authenticated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.

Returned Values

Attribute Description
sessionKey Session key that can be used in future request operations.

See "Authentication" topic in the Using Splunk's REST API chapter of this reference manual.

Example

Return a session key for the admin user that can be used in future request operations.


curl -k -u admin:pass  https://localhost:8089/services/auth/login \
	-d username=admin \
	-d password=pass


<response>
  <sessionKey>192fd3e46a31246da7ea7f109e7f95fd</sessionKey>
</response>


authentication/current-context

Allows for displaying the current user context

GET authentication/current-context

Lists one item named "context" which contains the name of the current user

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view current-context.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
username The Splunk username of the authenticated session owner.

Example

Retrieves the username of the authenticated session owner.


curl -k -u admin:pass https://localhost:8089/services/authentication/current-context


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>current-context</title>
  <id>https://localhost:8089/services/authentication/current-context</id>
  <updated>2011-07-10T23:28:20-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>context</title>
    <id>https://localhost:8089/services/authentication/current-context/context</id>
    <updated>2011-07-10T23:28:20-07:00</updated>
    <link href="/services/authentication/current-context/context" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/current-context/context" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="username">admin</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

authentication/httpauth-tokens

Allows for management of session tokens

GET authentication/httpauth-tokens

List all currently active session tokens

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view httpauth-tokens.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
authString The session key string, which is a unique identifier for this session.
searchId The search ID associated with this session, if it was created for a search job.

If it is a typical session for a login, this should be blank.

timeAccessed The last time this session has been touched.


userName The Splunk user name associated with this session.

Example

List the active session tokens for this Splunk instance.


curl -k -u admin:pass https://localhost:8089/services/authentication/httpauth-tokens


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>httpauth-tokens</title>
  <id>https://localhost:8089/services/authentication/httpauth-tokens</id>
  <updated>2011-07-12T13:51:56-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>795fc961f9cee34da3401cbe68f08659</title>
    <id>https://localhost:8089/services/authentication/httpauth-tokens/\
795fc961f9cee34da3401cbe68f08659</id>
    <updated>2011-07-12T13:51:56-07:00</updated>
    <link href="/services/authentication/httpauth-tokens/\
795fc961f9cee34da3401cbe68f08659" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/httpauth-tokens/\
795fc961f9cee34da3401cbe68f08659" rel="list"/>
    <link href="/services/authentication/httpauth-tokens/\
795fc961f9cee34da3401cbe68f08659" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="authString">795fc961f9cee34da3401cbe68f08659</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="searchId"/>
        <s:key name="timeAccessed">Tue Jul 12 13:51:56 2011</s:key>
        <s:key name="userName">admin</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

authentication/httpauth-tokens/{name}

DELETE authentication/httpauth-tokens/{name}

End the session associated with this token

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete httpauth-token.
404 httpauth-token does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

End the session by deleting the session token.


curl -k -u admin:pass --request DELETE \
        https://localhost:8089/services/authentication/httpauth-tokens/\
ddc919fd970184455f6c21819d5b1c82


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>httpauth-tokens</title>
  <id>https://localhost:8089/services/authentication/httpauth-tokens</id>
  <updated>2011-07-12T13:57:08-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET authentication/httpauth-tokens/{name}

Get information about a specific session token

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view httpauth-tokens.
404 httpauth-token does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
authString The session key string, which is a unique identifier for this session.
eai:attributes See Accessing Splunk resources
searchId The search ID associated with this session, if it was created for a search job.

If it is a typical session for a login, this should be blank.

timeAccessed The last time this session has been touched.


userName The Splunk user name associated with this session.

Example

Get information about the specified session token.


curl -k -u admin:pass \
	https://localhost:8089/services/authentication/httpauth-tokens/ddc919fd970184455f6c21819d5b1c82


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>httpauth-tokens</title>
  <id>https://localhost:8089/services/authentication/httpauth-tokens</id>
  <updated>2011-07-12T13:54:44-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>ddc919fd970184455f6c21819d5b1c82</title>
    <id>https://localhost:8089/services/authentication/httpauth-tokens/ddc919fd970184455f6c21819d5b1c82</id>
    <updated>2011-07-12T13:54:44-07:00</updated>
    <link href="/services/authentication/httpauth-tokens/ddc919fd970184455f6c21819d5b1c82" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/httpauth-tokens/ddc919fd970184455f6c21819d5b1c82" rel="list"/>
    <link href="/services/authentication/httpauth-tokens/ddc919fd970184455f6c21819d5b1c82" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="authString">ddc919fd970184455f6c21819d5b1c82</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="searchId"/>
        <s:key name="timeAccessed">Tue Jul 12 13:50:29 2011</s:key>
        <s:key name="userName">splunk-system-user</s:key>
      </s:dict>
    </content>
  </entry>
</feed>


authentication/users

Provides access to Splunk users.

Refer to About role-based user access in the Securing Splunk Enterprise manual for details about Splunk users, roles, and capabilities.

GET authentication/users

Returns a list of all the users registered on the server.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view users.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
defaultApp The default app for the user. When the user logs in to Splunk, this is the app we show.
defaultAppIsUserOverride Indicates whether the default app for the user overrides the default app for the user role.

The default app can come from this user's roles or the user itself.

defaultAppSourceRole Indicates which role determines the default app for the user. This is needed because a user can be a member of more than one role.
email Email address for the user.
password The user's password.
realname A full name to associate with the user.
roles Roles assigned to this user.
type The type of authentication system this user comes from, which can be any of the following:

LDAP

Scripted

Splunk

There is also a System type reserved for the Splunk system user.

tz Timezone to use when displaying dates for this user.

Example

Returns a list of all users registered on this Splunk instance.


curl -k -u admin:pass https://localhost:8089/services/authentication/users


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>users</title>
  <id>https://localhost:8089/services/authentication/users</id>
  <updated>2011-07-08T14:07:58-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/users/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>admin</title>
    <id>https://localhost:8089/services/authentication/users/admin</id>
    <updated>2011-07-08T14:07:58-07:00</updated>
    <link href="/services/authentication/users/admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/users/admin" rel="list"/>
    <link href="/services/authentication/users/admin" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="defaultApp">launcher</s:key>
        <s:key name="defaultAppIsUserOverride">0</s:key>
        <s:key name="defaultAppSourceRole">system</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="email">changeme@example.com</s:key>
        <s:key name="password">********</s:key>
        <s:key name="realname">Administrator</s:key>
        <s:key name="roles">
          <s:list>
            <s:item>admin</s:item>
          </s:list>
        </s:key>
        <s:key name="type">Splunk</s:key>
        <s:key name="tz"/>
      </s:dict>
    </content>
  </entry>
</feed>

POST authentication/users

Creates a new user.

When creating a user you must specify at least one role. You can specify one or more roles with the roles parameter, or you can use the createrole parameter to create a role for the user.

Refer to About role-based user access in the Securing Splunk Enterprise manual for details about Splunk users, roles, and capabilities.

Request

Name Type Required Default Description
name String
The username for the user to login to the Splunk platform.

usernames must be unique on the system.

password String
The user's password.
createrole Boolean false Flag to indicate that a new role should be created for the user. If set to "true", the new role user-<name> is created and assigned to the user. The <name> portion of the new role matches the name parameter value passed in with this POST request.

If set to "false", at least one existing role must be specified using the roles parameter for the POST request.
defaultApp String Specify a default app for the user.

The default app specified here overrides the default app inherited from the user's roles.

email String Specify an email address for the user.
realname String A full name to associate with the user.
restart_background_jobs Boolean Indicates whether to restart background search jobs when Splunk restarts.

If true, a background search job for this user that has not completed is restarted when Splunk restarts.

roles String One or more existing roles to assign to this user. At least one existing role is required if you are not using the createrole parameter to create a new role for the user. If you are using createrole to create a new role, you can use this parameter to specify additional roles to assign to the user.
tz String Timezone to use when displaying dates for this user.

Note: This parameter is new with Splunk 4.3.

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create user.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Creates the user named splunker, setting the password to changeme and setting the role to user.

After creating the role, perform the GET operation on /authentication/users/splunker to see details about the user.


curl -k -u admin:pass https://localhost:8089/services/authentication/users \
	-d name=splunker \
	-d password=changeme \
	-d roles=user


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>users</title>
  <id>https://localhost:8089/services/authentication/users</id>
  <updated>2011-07-08T14:08:17-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/users/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages>
    <s:msg type="WARN">This user will be disabled after the Enterprise Trial License expires</s:msg>
  </s:messages>
</feed>

authentication/users/{name}

DELETE authentication/users/{name}

Removes the user from the system.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete user.
404 User does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Deletes the splunker user.

The example for the POST operation for /authentication/users creates the splunker user.


curl -k -u admin:pass --request DELETE https://localhost:8089/services/authentication/users/splunker


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>users</title>
  <id>https://localhost:8089/services/authentication/users</id>
  <updated>2011-07-08T14:08:59-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/users/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET authentication/users/{name}

Returns information about the user.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view user.
404 User does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
defaultApp The default app for the user. When the user logs in to Splunk, this is the app we show.
defaultAppIsUserOverride Indicates whether the default app for the user overrides the default app for the user role.

The default app can come from this user's roles or the user itself.

defaultAppSourceRole Indicates which role determines the default app for the user. This is needed because a user can be a member of more than one role.
eai:attributes See Accessing Splunk resources
email Email address for the user.
password The user's password.
realname A full name to associate with the user.
roles Roles assigned to this user.
type The type of authentication system this user comes from, which can be any of the following:

LDAP

Scripted

Splunk

There is also a System type reserved for the Splunk system user.

tz Timezone to use when displaying dates for this user.

Example

Return information about the admin user.


curl -k -u admin:pass https://localhost:8089/services/authentication/users/admin


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>users</title>
  <id>https://localhost:8089/services/authentication/users</id>
  <updated>2011-07-08T14:08:34-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/users/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>admin</title>
    <id>https://localhost:8089/services/authentication/users/admin</id>
    <updated>2011-07-08T14:08:34-07:00</updated>
    <link href="/services/authentication/users/admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/users/admin" rel="list"/>
    <link href="/services/authentication/users/admin" rel="edit"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="defaultApp">launcher</s:key>
        <s:key name="defaultAppIsUserOverride">0</s:key>
        <s:key name="defaultAppSourceRole">system</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>defaultApp</s:item>
                <s:item>email</s:item>
                <s:item>password</s:item>
                <s:item>realname</s:item>
                <s:item>roles</s:item>
                <s:item>tz</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="email">changeme@example.com</s:key>
        <s:key name="password">********</s:key>
        <s:key name="realname">Administrator</s:key>
        <s:key name="roles">
          <s:list>
            <s:item>admin</s:item>
          </s:list>
        </s:key>
        <s:key name="type">Splunk</s:key>
        <s:key name="tz"/>
      </s:dict>
    </content>
  </entry>
</feed>

POST authentication/users/{name}

Update information about the user specified by {name}.

Request

Name Type Required Default Description
defaultApp String Specify a default app for the user.

The default app specified here overrides the default app inherited from the user's roles.

email String Specify an email address for the user.
password String The user's password.
realname String A full name to associate with the user.
restart_background_jobs Boolean Indicates whether to restart background search jobs when Splunk restarts.

If true, a background search job for this user that has not completed is restarted when Splunk restarts.

roles String A role to assign to this user. To assign multiple roles, send them in separate roles parameters.
tz String Timezone to use when displaying dates for this user.

Note: This parameter is new with Splunk 4.3.

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit user.
404 User does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
createrole Flag to indicate that a new role should be created for the user. If set to "true", the new role user.<name> is created and assigned to the user. The <name> portion of the new role matches the name parameter value passed in with this POST request.

If set to "false", at least one existing role must be specified using the roles parameter for the POST request.
defaultApp The default app for the user. When the user logs in to Splunk, this is the app we show.
defaultAppIsUserOverride Indicates whether the default app for the user overrides the default app for the user role.

The default app can come from this user's roles or the user itself.

defaultAppSourceRole Indicates which role determines the default app for the user. This is needed because a user can be a member of more than one role.
email Email address for the user.
password The user's password.
realname A full name to associate with the user.
restart_background_jobs Indicates whether to restart background search jobs when Splunk restarts.

If true, a background search job for this user that has not completed is restarted when Splunk restarts.

roles Roles assigned to this user. To assign multiple roles to the user, use multiple roles parameters. At least one role is required. If the role specified does not already exist and the createrole parameter is set to "true", a new role is created.
type The type of authentication system this user comes from, which can be any of the following:

LDAP

Scripted

Splunk

There is also a System type reserved for the Splunk system user.

tz Timezone to use when displaying dates for this user.

Example

Changes the defaultApp for the user splunker to the Splunk launcher app.


curl -k -u admin:pass https://localhost:8089/services/authentication/users/splunker \
	-d defaultApp=launcher


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>users</title>
  <id>https://localhost:8089/services/authentication/users</id>
  <updated>2011-07-08T14:08:53-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authentication/users/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>splunker</title>
    <id>https://localhost:8089/services/authentication/users/splunker</id>
    <updated>2011-07-08T14:08:53-07:00</updated>
    <link href="/services/authentication/users/splunker" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authentication/users/splunker" rel="list"/>
    <link href="/services/authentication/users/splunker" rel="edit"/>
    <link href="/services/authentication/users/splunker" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="defaultApp">launcher</s:key>
        <s:key name="defaultAppIsUserOverride">1</s:key>
        <s:key name="defaultAppSourceRole">system</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="email"/>
        <s:key name="password">********</s:key>
        <s:key name="realname"/>
        <s:key name="roles">
          <s:list>
            <s:item>user</s:item>
          </s:list>
        </s:key>
        <s:key name="type">Splunk</s:key>
        <s:key name="tz"/>
      </s:dict>
    </content>
  </entry>
</feed>


authorization/capabilities

Provides access to Splunk's capability authorization system.

Refer to About role-based user access in the Securing Splunk Enterprise manual for details about Splunk users, roles, and capabilities.

GET authorization/capabilities

List all system capabiilities.

Refer to the List of available capabilities in the Securing Splunk Enterprise manual for details.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view capabilities.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
capabilities The list of all Splunk capabilities.

Refer to the List of available capabilities in the Securing Splunk Enterprise manual for details.

Example

Lists all capabilities known to Splunk.


curl -k -u admin:pass https://localhost:8089/services/authorization/capabilities


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>capabilities</title>
  <id>https://localhost:8089/services/authorization/capabilities</id>
  <updated>2011-07-10T23:32:25-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>capabilities</title>
    <id>https://localhost:8089/services/authorization/capabilities/capabilities</id>
    <updated>2011-07-10T23:32:25-07:00</updated>
    <link href="/services/authorization/capabilities/capabilities" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authorization/capabilities/capabilities" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="capabilities">
          <s:list>
            <s:item>admin_all_objects</s:item>
            <s:item>change_authentication</s:item>
            <s:item>change_own_password</s:item>
            <s:item>delete_by_keyword</s:item>
            <s:item>edit_deployment_client</s:item>
            . . . <!-- items elided for brevity -->
            <s:item>restart_splunkd</s:item>
            <s:item>rtsearch</s:item>
            <s:item>schedule_search</s:item>
            <s:item>search</s:item>
            <s:item>use_file_operator</s:item>
          </s:list>
        </s:key>
        <!-- eai:acl nodes elided for brevity. -->
      </s:dict>
    </content>
  </entry>
</feed>

authorization/capabilities/{name}

GET authorization/capabilities/{name}

List a particular system capability name. This does not list any further information besides the name.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view capabilities.
404 Capability does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Identical to accessing authorization/capabilities. Note that "capabilities" is the only valid name here.


curl -k -u admin:pass https://localhost:8089/services/authorization/capabilities/capabilities


See response for authorization/capabilities.


authorization/roles

Provides access to Splunk user roles.

Refer to About role-based user access in the Securing Splunk Enterprise manual for details about Splunk users, roles, and capabilities.

GET authorization/roles

Lists all roles and the permissions for each role. Refer to About role-based user access in the Securing Splunk Enterprise manual for details about Splunk users, roles, and capabilities.

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view roles.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
capabilities A list of capabilities assigned to this role.

The Securing Splunk Enterprise manual describes all capabilities.

defaultApp The name of the app to use as the default app for this role.

A user-specific default app overrides this.

imported_capabilities A list of capabilites for this role that were made available from imported roles.
imported_roles List of imported roles for this role.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

imported_rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.

imported_rtSrchJObsQuota specifies the quota imported from other roles.

imported_srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.

imported_srchDiskQuota specifies the quota for this role that have imported from other roles.

imported_srchFilter Search string, imported from other roles, that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

imported_srchIndexesAllowed A list of indexes, imported from other roles, this role has permissions to search.
imported_srchIndexesDefault A list of indexes, imported from other roles, that this role defaults to when no index is specified in a search.
imported_srchJobsQuota The maximum number of historical searches for this role that are imported from other roles.
imported_srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

imported_srchTimeWin specifies the limit from imported roles.

rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.
srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter Search string that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

srchIndexesAllowed A list of indexes this role has permissions to search.
srchIndexesDefault List of search indexes that default to this role when no index is specified.
srchJobsQuota The maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

Example

Lists all the roles defined for this Splunk instance.


curl -k -u admin:pass https://localhost:8089/services/authorization/roles


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>roles</title>
  <id>https://localhost:8089/services/authorization/roles</id>
  <updated>2011-07-08T13:52:32-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authorization/roles/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>admin</title>
    <id>https://localhost:8089/services/authorization/roles/admin</id>
    <updated>2011-07-08T13:52:32-07:00</updated>
    <link href="/services/authorization/roles/admin" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authorization/roles/admin" rel="list"/>
    <link href="/services/authorization/roles/admin" rel="edit"/>
    <link href="/services/authorization/roles/admin" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="capabilities">
          <s:list>
            <s:item>admin_all_objects</s:item>
            <s:item>change_authentication</s:item>
            <s:item>edit_deployment_client</s:item>
            <!-- additional items elided for brevity. -->
            <s:item>list_httpauths</s:item>
            <s:item>rest_apps_management</s:item>
            <s:item>restart_splunkd</s:item>
          </s:list>
        </s:key>
        <s:key name="defaultApp"/>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="imported_capabilities">
          <s:list>
            <s:item>change_own_password</s:item>
            <s:item>get_metadata</s:item>
            <s:item>get_typeahead</s:item>
            <!-- additional items elided for brevity. -->
            <s:item>schedule_search</s:item>
            <s:item>search</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_roles">
          <s:list>
            <s:item>power</s:item>
            <s:item>user</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_rtSrchJobsQuota">20</s:key>
        <s:key name="imported_srchDiskQuota">500</s:key>
        <s:key name="imported_srchFilter"/>
        <s:key name="imported_srchIndexesAllowed">
          <s:list>
            <s:item>*</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_srchIndexesDefault">
          <s:list>
            <s:item>main</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_srchJobsQuota">10</s:key>
        <s:key name="imported_srchTimeWin">-1</s:key>
        <s:key name="rtSrchJobsQuota">100</s:key>
        <s:key name="srchDiskQuota">10000</s:key>
        <s:key name="srchFilter">*</s:key>
        <s:key name="srchIndexesAllowed">
          <s:list>
            <s:item>*</s:item>
            <s:item>_*</s:item>
          </s:list>
        </s:key>
        <s:key name="srchIndexesDefault">
          <s:list>
            <s:item>main</s:item>
            <s:item>os</s:item>
          </s:list>
        </s:key>
        <s:key name="srchJobsQuota">50</s:key>
        <s:key name="srchTimeWin">0</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST authorization/roles

Create a user role. Refer to About role-based user access in the Securing Splunk Enterprise manual for details about Splunk users, roles, and capabilities.

Request

Name Type Required Default Description
name String
The name of the user role to create.
capabilities String A capability to assign to this role. To send multiple capabilities, send this argument multiple times.

Roles inherit all capabilities from imported roles. For more information, refer to About defining roles with capabilities.

cumulativeRTSrchJobsQuota Number Maximum number of concurrently running real-time searches that all members of this role can have.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

cumulativeSrchJobsQuota Number Maximum number of concurrently running historical searches that all members of this role can have.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

defaultApp String Specify the name of the app to use as the default app for the role.A user-specific default app will override this.

The name you specify is the name of the folder containing the app.

imported_roles String Specify a role to import attributes from. Specify many of these separately to import multiple roles. By default a role imports no other roles.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

Default Splunk roles are:

  • admin
  • can_delete
  • power
  • user

You can specify additional roles that have been created.

rtSrchJobsQuota Number Specify the maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchDiskQuota Number Specifies the maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter String Specify a search string that restricts the scope of searches run by this role. Search results for this role only show events that also match the search string you specify. In the case that a user has multiple roles with different search filters, they are combined with an OR.

The search string can include source, host, index, eventtype, sourcetype, search fields, *, OR and, AND.

Example: "host=web* OR source=/var/log/*"

Note: You can also use the srchIndexesAllowed and srchIndexesDefault parameters to limit the search on indexes.

srchIndexesAllowed String An index this role has permissions to search. To set several of these, pass this argument several times. These may be wildcarded, but the index name must begin with an underscore to match internal indexes.

Search indexes available by default from Splunk include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main

You can also specify other search indexes that have been added to the server.

srchIndexesDefault String For this role, indexes to search when no index is specified.

These indexes can be wildcarded, with the exception that '*' does not match internal indexes. To match internal indexes, start with '_'. All internal indexes are represented by '_*'.

A user with this role can search other indexes using "index= "

For example, "index=special_index".

Search indexes available by default from Splunk include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main
  • other search indexes that have been added to the server
srchJobsQuota Number The maximum number of concurrent searches a user with this role is allowed to run. In the event of many roles per user, the maximum of these quotas is applied.
srchTimeWin Number Maximum time span of a search, in seconds.

By default, searches are not limited to any specific time window. To override any search time windows from imported roles, set srchTimeWin to '0', as the 'admin' role does.

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create role.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Creates a new role, SplunkUser that imports the capabilities of the user role and sets the defaultApp to the Splunk search app.

After creating the role, perform the GET operation on /authorization/roles/SplunkUser to verify that the role was created.


curl -k -u admin:pass https://localhost:8089/services/authorization/roles \
	-d name=SplunkUser \
	-d imported_roles=user \
	-d defaultApp=search


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>roles</title>
  <id>https://localhost:8089/services/authorization/roles</id>
  <updated>2011-07-08T13:52:47-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authorization/roles/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages>
    <s:msg type="WARN">This role will be disabled after the Enterprise Trial License expires</s:msg>
  </s:messages>
</feed>

authorization/roles/{name}

DELETE authorization/roles/{name}

Deletes the role specified by {name}.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete role.
404 Role does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Deletes the SplunkUser role created in the POST example for /authorization/roles.

After deleting the role, run the GET operation for /authorization/roles to verify that the role has been deleted.


curl -k -u admin:pass --request DELETE \
	https://localhost:8089/services/authorization/roles/SplunkUser


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>roles</title>
  <id>https://localhost:8089/services/authorization/roles</id>
  <updated>2011-07-08T13:53:06-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authorization/roles/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET authorization/roles/{name}

Lists the permissions for the role specified by {name}.

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view role.
404 Role does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
capabilities A list of capabilities assigned to this role.

The Securing Splunk Enterprise manual describes all capabilities.

defaultApp The name of the app to use as the default app for this role.

A user-specific default app overrides this.

eai:attributes See Accessing Splunk resources
imported_capabilities A list of capabilites for this role that were made available from imported roles.
imported_roles List of imported roles for this role.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

imported_rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.

imported_rtSrchJObsQuota specifies the quota imported from other roles.

imported_srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.

imported_srchDiskQuota specifies the quota for this role that have imported from other roles.

imported_srchFilter Search string, imported from other roles, that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

imported_srchIndexesAllowed A list of indexes, imported from other roles, this role has permissions to search.
imported_srchIndexesDefault A list of indexes, imported from other roles, that this role defaults to when no index is specified in a search.
imported_srchJobsQuota The maximum number of historical searches for this role that are imported from other roles.
imported_srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

imported_srchTimeWin specifies the limit from imported roles.

rtSrchJobsQuota The maximum number of concurrent real time search jobs for this role. This count is independent from the normal search jobs limit.
srchDiskQuota The maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter Search string that restricts the scope of searches run by this role.

Search results for this role only show events that also match this search string. When a user has multiple roles with different search filters, they are combined with an OR.

srchIndexesAllowed A list of indexes this role has permissions to search.
srchIndexesDefault List of search indexes that default to this role when no index is specified.
srchJobsQuota The maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchTimeWin Maximum time span of a search, in seconds.

0 indicates searches are not limited to any specific time window.

Example

List the permissions for the SplunkUser role created for the POST operation example for /authorization/roles.


curl -k -u admin:pass https://localhost:8089/services/authorization/roles/SplunkUser


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>roles</title>
  <id>https://localhost:8089/services/authorization/roles</id>
  <updated>2011-07-08T13:52:57-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authorization/roles/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
  <entry>
    <title>splunkuser</title>
    <id>https://localhost:8089/services/authorization/roles/splunkuser</id>
    <updated>2011-07-08T13:52:57-07:00</updated>
    <link href="/services/authorization/roles/splunkuser" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/authorization/roles/splunkuser" rel="list"/>
    <link href="/services/authorization/roles/splunkuser" rel="edit"/>
    <link href="/services/authorization/roles/splunkuser" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="capabilities">
          <s:list/>
        </s:key>
        <s:key name="defaultApp">search</s:key>
        <!-- eai:acl nodes elided for brevity. -->
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>capabilities</s:item>
                <s:item>defaultApp</s:item>
                <s:item>imported_roles</s:item>
                <s:item>rtSrchJobsQuota</s:item>
                <s:item>srchDiskQuota</s:item>
                <s:item>srchFilter</s:item>
                <s:item>srchIndexesAllowed</s:item>
                <s:item>srchIndexesDefault</s:item>
                <s:item>srchJobsQuota</s:item>
                <s:item>srchTimeWin</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="imported_capabilities">
          <s:list>
            <s:item>change_own_password</s:item>
            <s:item>get_metadata</s:item>
            <s:item>get_typeahead</s:item>
            <s:item>list_inputs</s:item>
            <s:item>request_remote_tok</s:item>
            <s:item>rest_apps_view</s:item>
            <s:item>rest_properties_get</s:item>
            <s:item>rest_properties_set</s:item>
            <s:item>search</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_roles">
          <s:list>
            <s:item>user</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_rtSrchJobsQuota">6</s:key>
        <s:key name="imported_srchDiskQuota">100</s:key>
        <s:key name="imported_srchFilter"/>
        <s:key name="imported_srchIndexesAllowed">
          <s:list>
            <s:item>*</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_srchIndexesDefault">
          <s:list>
            <s:item>main</s:item>
          </s:list>
        </s:key>
        <s:key name="imported_srchJobsQuota">3</s:key>
        <s:key name="imported_srchTimeWin">-1</s:key>
        <s:key name="rtSrchJobsQuota">0</s:key>
        <s:key name="srchDiskQuota">0</s:key>
        <s:key name="srchFilter"/>
        <s:key name="srchIndexesAllowed">
          <s:list/>
        </s:key>
        <s:key name="srchIndexesDefault">
          <s:list/>
        </s:key>
        <s:key name="srchJobsQuota">0</s:key>
        <s:key name="srchTimeWin">-1</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST authorization/roles/{name}

Updates the role specified by {name}.

Request

Name Type Required Default Description
capabilities String A capability to assign to this role. To send multiple capabilities, send this argument multiple times.

Roles inherit all capabilities from imported roles. For more information, refer to About defining roles with capabilities.

cumulativeRTSrchJobsQuota Number Maximum number of concurrently running real-time searches that all members of this role can have.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

cumulativeSrchJobsQuota Number Maximum number of concurrently running historical searches that all members of this role can have.

Note: If a user belongs to multiple roles then the user first consumes searches from the roles with the largest cumulative search quota. When the quota of a role is completely used up then roles with lower quotas are examined.

defaultApp String Specify the name of the app to use as the default app for the role.A user-specific default app will override this.

The name you specify is the name of the folder containing the app.

imported_roles String Specify a role to import attributes from. Specify many of these separately to import multiple roles. By default a role imports no other roles.

Importing other roles imports all aspects of that role, such as capabilities and allowed indexes to search. In combining multiple roles, the effective value for each attribute is value with the broadest permissions.

Default Splunk roles are:

  • admin
  • can_delete
  • power
  • user

You can specify additional roles that have been created.

rtSrchJobsQuota Number Specify the maximum number of concurrent real time search jobs for this role.

This count is independent from the normal search jobs limit.

srchDiskQuota Number Specifies the maximum disk space in MB that can be used by a user's search jobs. For example, 100 limits this role to 100 MB total.
srchFilter String Specify a search string that restricts the scope of searches run by this role. Search results for this role only show events that also match the search string you specify. In the case that a user has multiple roles with different search filters, they are combined with an OR.

The search string can include source, host, index, eventtype, sourcetype, search fields, *, OR and, AND.

Example: "host=web* OR source=/var/log/*"

Note: You can also use the srchIndexesAllowed and srchIndexesDefault parameters to limit the search on indexes.

srchIndexesAllowed String An index this role has permissions to search. To set several of these, pass this argument several times. These may be wildcarded, but the index name must begin with an underscore to match internal indexes.

Search indexes available by default from Splunk include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main

You can also specify other search indexes that have been added to the server.

srchIndexesDefault String For this role, indexes to search when no index is specified.

These indexes can be wildcarded, with the exception that '*' does not match internal indexes. To match internal indexes, start with '_'. All internal indexes are represented by '_*'.

A user with this role can search other indexes using "index= "

For example, "index=special_index".

Search indexes available by default from Splunk include:

  • All internal indexes
  • All non-internal indexes
  • _audit
  • _blocksignature
  • _internal
  • _thefishbucket
  • history
  • main
  • other search indexes that have been added to the server
srchJobsQuota Number The maximum number of concurrent searches a user with this role is allowed to run. In the event of many roles per user, the maximum of these quotas is applied.
srchTimeWin Number Maximum time span of a search, in seconds.

By default, searches are not limited to any specific time window. To override any search time windows from imported roles, set srchTimeWin to '0', as the 'admin' role does.

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit role.
404 Role does not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

No values returned for this request.

Example

Updates the SplunkUser role to change the default application to launcher. The SplunkUser role is created in the example for the POST operation for /authorization/roles.

After updating the role, run the GET operation for /authorization/roles/SplunkUser to see the updated default application.


curl -k -u admin:pass https://localhost:8089/services/authorization/roles/SplunkUser \
	-d defaultApp=launcher


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>roles</title>
  <id>https://localhost:8089/services/authorization/roles</id>
  <updated>2011-07-08T13:53:02-07:00</updated>
  <generator version="102807"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/authorization/roles/_new" rel="create"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>


storage/passwords

Allows for management of secure credentials. The password is encrypted with a secret key that resides on the same machine. The clear text passwords can be accessed by users that have access to this service. Only users with admin priviledges can access this endpoint.

GET storage/passwords

List available credentials

Request

Name Type Required Default Description
count Number 30 Indicates the maximum number of entries to return. To return all entries, specify 0.
offset Number 0 Index for first item to return.
search String Search expression to filter the response. The response matches field values against the search expression. For example:

search=foo matches any object that has "foo" as a substring in a field. search=field_name%3Dfield_value restricts the match to a single field. URI-encoding is required in this example.

sort_dir Enum asc Valid values: (asc | desc)

Indicates whether to sort returned entries in ascending or descending order.

sort_key String name Field to use for sorting.
sort_mode Enum auto Valid values: (auto | alpha | alpha_case | num)

Indicates the collating sequence for sorting the returned entries. auto: If all values of the field are numbers, collate numerically. Otherwise, collate alphabetically. alpha: Collate alphabetically. alpha_case: Collate alphabetically, case-sensitive. num: Collate numerically.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view credentials.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
clear_password Plain text version of password.
eai:acl See Access control lists for Splunk objects
encr_password Encrypted password, as it is stored.
password Masked version of the password.

This is always stored as "********".

realm The realm in which the credentials are valid.
username The Splunk username for the credentials.

Example

Lists stored credentials, showing the clear text and encrypted password.


curl -k -u admin:pass https://localhost:8089/services/storage/passwords


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>passwords</title>
  <id>https://localhost:8089/services/storage/passwords</id>
  <updated>2011-07-05T21:39:56-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/storage/passwords/_new" rel="create"/>
  <link href="/services/storage/passwords/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>:splunker:</title>
    <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A</id>
    <updated>2011-07-05T21:39:56-07:00</updated>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="list"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="edit"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="clear_password">changeme</s:key>
        <s:key name="eai:acl"> . . .</s:key>
        <s:key name="encr_password">$1$oPmwi5i6DcNz</s:key>
        <s:key name="password">********</s:key>
        <s:key name="realm"></s:key>
        <s:key name="username">splunker</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST storage/passwords

Create/edit new credentials

Request

Name Type Required Default Description
name String
Username for the credentials
password String
The password for the credentials - this is the only part of the credentials that will be stored securely
realm String The credential realm

Response Codes

Status Code Description
201 Created successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to create credentials.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
clear_password Plain text version of password.
eai:acl See Access control lists for Splunk objects
encr_password Encrypted password, as it is stored.

This is always stored as "********".

password The plain text version of the password.
realm The realm in which the credentials are valid.
username The Splunk username for the credentials.

Example

Creates stored credentials for the user, splunker.


curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/storage/passwords \
	-d name=splunker \
	-d password=changeme


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>passwords</title>
  <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords</id>
  <updated>2011-07-05T21:39:41-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/nobody/search/storage/passwords/_new" rel="create"/>
  <link href="/servicesNS/nobody/search/storage/passwords/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>:splunker:</title>
    <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A</id>
    <updated>2011-07-05T21:39:41-07:00</updated>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="list"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="edit"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="clear_password">changeme</s:key>
        <s:key name="eai:acl"> . . </s:key>
        <s:key name="encr_password">$1$oPmwi5i6DcNz</s:key>
        <s:key name="password">********</s:key>
        <s:key name="realm"></s:key>
        <s:key name="username">splunker</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

storage/passwords/{name}

DELETE storage/passwords/{name}

Delete the identified credentials

Request

No parameters for this request.

Response Codes

Status Code Description
200 Deleted successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to delete credentials.
404 Credentials do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

No values returned for this request.

Example

Deletes the stored credentials for the user, splunker.


curl -k -u admin:pass --request DELETE \
	https://localhost:8089/servicesNS/nobody/search/storage/passwords/:splunker:


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:s="http://dev.splunk.com/ns/rest">
  <title>passwords</title>
  <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords</id>
  <updated>2011-07-12T14:48:50-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/nobody/search/storage/passwords/_new" rel="create"/>
  <link href="/servicesNS/nobody/search/storage/passwords/_reload" rel="_reload"/>
  <!-- opensearch nodes elided for brevity. -->
  <s:messages/>
</feed>

GET storage/passwords/{name}

List only the credentials identified by the given id

Request

No parameters for this request.

Response Codes

Status Code Description
200 Listed successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
403 Insufficient permissions to view credentials.
404 Credentials do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.

Returned Values

Attribute Description
clear_password Plain text version of password.
eai:acl See Access control lists for Splunk objects
eai:attributes See Accessing Splunk resources
encr_password Encrypted password, as it is stored.

This is always stored as "********".

password Plain text version of the password.
realm The realm in which the credentials are valid.
username The Splunk username for the credentials.

Example

Lists stored credentials for the user splunker.


curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/storage/passwords/splunker


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>passwords</title>
  <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords</id>
  <updated>2011-07-05T21:50:10-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/nobody/search/storage/passwords/_new" rel="create"/>
  <link href="/servicesNS/nobody/search/storage/passwords/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>:splunker:</title>
    <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A</id>
    <updated>2011-07-05T21:50:10-07:00</updated>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="list"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="edit"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="clear_password">changeme</s:key>
        <s:key name="eai:acl"> . . . </s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list/>
            </s:key>
            <s:key name="requiredFields">
              <s:list>
                <s:item>password</s:item>
              </s:list>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="encr_password">$1$oPmwi5i6DcNz</s:key>
        <s:key name="password">********</s:key>
        <s:key name="realm"></s:key>
        <s:key name="username">splunker</s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST storage/passwords/{name}

Edit the identified credentials.

Request

Name Type Required Default Description
password String
The password for the credentials - this is the only part of the credentials that will be stored securely

Response Codes

Status Code Description
200 Updated successfully.
400 Request error. See response body for details.
401 Authentication failure: must pass valid credentials with request.
402 The Splunk license in use has disabled this feature.
403 Insufficient permissions to edit credentials.
404 Credentials do not exist.
409 Request error: this operation is invalid for this item. See response body for details.
500 Internal server error. See response body for details.
503 This feature has been disabled in Splunk configuration files.

Returned Values

Attribute Description
clear_password Plain text version of password.
eai:acl See Access control lists for Splunk objects
encr_password Encrypted password, as it is stored.

This is always stored as "********".

password The plain text version of the password.
realm The realm in which the credentials are valid.
username The Splunk username for the credentials.

Example

Change the stored credentials for the user splunker, by setting the password to pass.


curl -k -u admin:pass https://localhost:8089/servicesNS/nobody/search/storage/passwords/splunker \
	-d password=pass


<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:s="http://dev.splunk.com/ns/rest"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>passwords</title>
  <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords</id>
  <updated>2011-07-05T21:54:31-07:00</updated>
  <generator version="102824"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/servicesNS/nobody/search/storage/passwords/_new" rel="create"/>
  <link href="/servicesNS/nobody/search/storage/passwords/_reload" rel="_reload"/>
  <opensearch:totalResults>1</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>:splunker:</title>
    <id>https://localhost:8089/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A</id>
    <updated>2011-07-05T21:54:31-07:00</updated>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="alternate"/>
    <author>
      <name>admin</name>
    </author>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="list"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="edit"/>
    <link href="/servicesNS/nobody/search/storage/passwords/%3Asplunker%3A" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="clear_password">pass</s:key>
        <s:key name="eai:acl"> . . . </s:key>
        <s:key name="encr_password">$1$s/Cilqo=</s:key>
        <s:key name="password">********</s:key>
        <s:key name="realm"></s:key>
        <s:key name="username">splunker</s:key>
      </s:dict>
    </content>
  </entry>
</feed>
PREVIOUS
REST API Endpoints
  NEXT
Applications

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters