Documentation > Splunk > REST API Reference > Access control

REST API Reference

 


REST API reference
Using Splunk's REST API

Access control

Contents

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.

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 -1.
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/current-context/{name}

GET authentication/current-context/{name}

Displays an item (always named "context") that contains the name of the current 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 current-context.
404 current-context 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 retrieving authentication/current-context. Note that "context" is the only valid name here. 


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


See response for authentication/current-context.


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 -1.
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 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 -1.
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 manual for details about Splunk users, roles, and capabilities.

Request

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

usernames must be unique on the system.

password String
✓
 The user's password.
createrole String The name of a role to create for the user. After creating the role, you can later edit that role to specify what access that user has to Splunk.
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 A role to assign to this user. To assign multiple roles, send them in separate roles parameters.

When creating a user, at least one role is required. Either specify one or more roles with this parameter or create a role using the createrole parameter.

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.

When creating a user, at least one role is required. Either specify one or more roles with this parameter or create a role using the createrole parameter.

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 The name of a role created for the user.

You can edit that role to specify what access that user has to Splunk.

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.
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 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 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 -1.
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 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 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 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 -1.
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 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 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.

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 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.

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.

Note: This endpoint is new for Splunk 4.3. It replaces the deprecated endpoint accessible from /admin/passwords/.

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 -1.
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.

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, 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>
Retrieved from "http://docs.splunk.com/Documentation/Splunk/5.0.2/RESTAPI/RESTaccess"

This documentation applies to the following versions of Splunk: 5.0 , 5.0.1 , 5.0.2 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!