Skip to content

Commit fecfd35

Browse files
kanchana-mongodbkanchana-mongodb
authored
DOCSP-11877 docs for global api keys (#225)
* DOCSP-11877 docs for global api keys * DOCSP-11877 updates for copy review feedback * DOCSP-11877 fix for command syntax
1 parent b9b8586 commit fecfd35

8 files changed

+837
-0
lines changed

‎source/includes/list-table-global-roles.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. list-table::
2+
:widths: 50 50
3+
:header-rows: 1
4+
5+
* - Role Value in API
6+
- Role
7+
* - ``GLOBAL_AUTOMATION_ADMIN``
8+
- :authrole:`Global Automation Admin`
9+
* - ``GLOBAL_BACKUP_ADMIN``
10+
- :authrole:`Global Backup Admin`
11+
* - ``GLOBAL_MONITORING_ADMIN``
12+
- :authrole:`Global Monitoring Admin`
13+
* - ``GLOBAL_OWNER``
14+
- :authrole:`Global Owner`
15+
* - ``GLOBAL_READ_ONLY``
16+
- :authrole:`Global Read Only`
17+
* - ``GLOBAL_USER_ADMIN``
18+
- :authrole:`Global User Admin`

‎source/reference/access.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424
:ref:`project apikey <mcli-reference-iam-project-apikeys>`
2525
Manage |api| keys in your project.
2626

27+
:ref:`globalapikey <mcli-reference-iam-global-apikeys>`
28+
Manage Global |api| Keys in your |onprem| instance.
29+
2730
.. class:: hidden
2831

2932
.. toctree::
@@ -33,3 +36,4 @@
3336
Organization API Keys </reference/iam/organization-apikey-commands>
3437
Projects </reference/iam/project-commands>
3538
Project API Keys </reference/iam/project-apikey-commands>
39+
Global API Keys </reference/iam/global-apikey-commands>

‎source/reference/iam/global-apikey-commands.txt

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _mcli-reference-iam-global-apikeys:
2+
3+
=======================
4+
Global API Key Commands
5+
=======================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. toctree::
16+
:titlesonly:
17+
18+
Create a Global API Key <iam-global-apikey-create>
19+
List Global API Keys <iam-global-apikey-list>
20+
Describe a Global API Key <iam-global-apikey-describe>
21+
Update a Global API Key <iam-global-apikey-update>
22+
Delete a Global API Key <iam-global-apikey-delete>
23+

‎source/reference/iam/iam-global-apikey-create.txt

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _mcli-iam-global-apikey-create:
2+
3+
================================
4+
mongocli iam globalApiKey create
5+
================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
The ``iam globalApiKey create`` command creates a new Global
16+
|api| Key for the specified |mms| instance. You must have the
17+
:opsmgr:`Global Owner </reference/user-roles/#Global-Owner>` role
18+
to create a Global |api| key. You can also create the key through
19+
the |mms| :opsmgr:`UI
20+
</admin/general/api-keys-page/#add-a-global-api-key>` and
21+
:opsmgr:`API </reference/api/api-keys/global/create-one-global-api-key/>`.
22+
23+
.. _mcli-iam-global-apikey-create-syntax:
24+
25+
Syntax
26+
------
27+
28+
.. code-block:: text
29+
30+
mongocli iam globalApiKey|globalApiKeys create
31+
--desc "<description-of-key>"
32+
[ --output|-o <output-format> ]
33+
[ --profile|-P <profile-name> ]
34+
--role <list-of-roles>
35+
36+
.. include:: /includes/fact-command-line-help.rst
37+
38+
.. _mcli-iam-global-apikey-create-options:
39+
40+
Options
41+
-------
42+
43+
.. list-table::
44+
:header-rows: 1
45+
:widths: 20 10 60 10
46+
47+
* - Option
48+
- Type
49+
- Description
50+
- Required?
51+
52+
* - ``--desc``
53+
- string
54+
- Description of the |api| key. This description can’t be longer
55+
than 250 characters.
56+
- yes
57+
58+
* - ``--output``, ``-o``
59+
- string
60+
- .. include:: /includes/extracts/fact-basic-options-output.rst
61+
- no
62+
63+
* - ``--profile``, ``-P``
64+
- string
65+
- Name of the profile where your credentials are saved. If omitted,
66+
uses the {+default-profile+}. To learn more about
67+
creating a profile, see :ref:`mcli-configure`.
68+
69+
You must have credentials with the :authrole:`Global Owner` role to
70+
create a Global |api| Key.
71+
- no
72+
73+
* - ``--role``
74+
- string
75+
- Role or roles to assign to the |api| key. To assign more than
76+
one role, you can specify each role with a ``--role`` flag or
77+
specify the roles in a comma-separated list with one ``--role``
78+
flag. Global roles accepted by default include:
79+
80+
.. include:: /includes/list-table-global-roles.rst
81+
82+
- yes
83+
84+
.. _mcli-iam-global-apikey-create-output:
85+
86+
Output
87+
------
88+
89+
If the command succeeds, it prints the following output to the terminal.
90+
If the command returns errors, see :ref:`Troubleshooting
91+
<troubleshooting>` for recommended solutions.
92+
93+
.. code-block:: sh
94+
:copyable: false
95+
96+
API Key '<api-key-id>' created.
97+
Public API Key <public-key>
98+
Private API Key <private-key>
99+
100+
.. warning:: Copy and Save Public and Private Keys
101+
102+
{+mcli+} returns the Private |api| Key only once. After running this
103+
command, immediately copy, save, and secure both the Public and
104+
Private |api| Keys.
105+
106+
For the complete list of |json| fields returned by the command, see the
107+
public API :opsmgr:`reference
108+
</reference/api/api-keys/global/create-one-global-api-key/#response>`.
109+
The default output contains only a subset of the fields returned by this
110+
command.
111+
112+
.. _mcli-iam-global-apikey-create-examples:
113+
114+
Examples
115+
--------
116+
117+
.. tabs::
118+
119+
.. tab:: Default Output
120+
:tabid: default-output
121+
122+
The following command creates a Global |api| Key using a profile
123+
named ``om-admin``, which contains the ``Organization Owner``
124+
credentials, the organization ID, and specifies the |onprem|
125+
service. The output is returned in the default format.
126+
127+
.. code-block:: sh
128+
129+
mongocli iam globalApiKey create --desc "My Global API key" --role "GLOBAL_READ_ONLY","GLOBAL_USER_ADMIN" --profile om-admin
130+
131+
The previous command creates the |api| key and
132+
prints the following to the terminal.
133+
134+
.. code-block:: json
135+
:copyable: false
136+
137+
API Key '5f3d8790c12345678903c8d66' created.
138+
Public API Key abcdefgh
139+
Private API Key b4d12345-b4a3-1234-b24e-729b3f35642d
140+
141+
.. tab:: JSON Output
142+
:tabid: json-output
143+
144+
The following command creates a Global |api| Key using a profile
145+
named ``om-admin``, which contains the ``Organization Owner``
146+
credentials, the organization ID, and specifies the |onprem|
147+
service. The output is returned in |json| format.
148+
149+
.. code-block:: sh
150+
151+
mongocli iam globalApiKey create --desc "My Global API key" --role "GLOBAL_READ_ONLY","GLOBAL_USER_ADMIN" --profile om-admin --output json
152+
153+
The previous command creates the |api| key and
154+
prints the following to the terminal in |json| format.
155+
156+
.. code-block:: json
157+
:copyable: false
158+
159+
{
160+
"id": "5f3d8ea3c9022019903c9fce",
161+
"desc": "My Global API key",
162+
"roles": [
163+
{
164+
"roleName": "GLOBAL_READ_ONLY"
165+
},
166+
{
167+
"roleName": "GLOBAL_USER_ADMIN"
168+
}
169+
],
170+
"privateKey": "b4d12345-b4a3-1234-b24e-729b3f35642d",
171+
"publicKey": "abcdefgh"
172+
}

‎source/reference/iam/iam-global-apikey-delete.txt

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _mcli-iam-global-apikey-delete:
2+
3+
================================
4+
mongocli iam globalApiKey delete
5+
================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
The ``iam globalApiKey delete`` command deletes the specified
16+
Global |api| Key. You must confirm the operation
17+
when you run this command without the ``--force`` option. You
18+
can also delete a Global |api| Key using the |onprem|
19+
:opsmgr:`UI </admin/general/api-keys-page/#delete-a-global-api-key>` and
20+
:opsmgr:`API </reference/api/api-keys/global/delete-one-global-api-key/>`.
21+
22+
.. _mcli-iam-global-apikey-delete-syntax:
23+
24+
Syntax
25+
------
26+
27+
.. code-block:: text
28+
29+
mongocli iam globalApiKey|globalApiKeys delete|rm <api-key-id>
30+
[ --force ]
31+
[ --profile|-P <profile-name> ]
32+
33+
.. include:: /includes/fact-command-line-help.rst
34+
35+
.. _mcli-iam-global-apikey-delete-arguments:
36+
37+
Arguments
38+
---------
39+
40+
.. list-table::
41+
:header-rows: 1
42+
:widths: 20 10 60 10
43+
44+
* - Argument
45+
- Type
46+
- Description
47+
- Required?
48+
49+
* - ``<api-key-id>``
50+
- string
51+
- Unique identifier of the Global API Key to delete.
52+
- yes
53+
54+
.. _mcli-iam-global-apikey-delete-options:
55+
56+
Options
57+
-------
58+
59+
.. list-table::
60+
:header-rows: 1
61+
:widths: 20 10 60 10
62+
63+
* - Option
64+
- Type
65+
- Description
66+
- Required?
67+
68+
* - ``--force``
69+
-
70+
- Flag that indicates that the |api| key can
71+
be deleted without requiring confirmation.
72+
- no
73+
74+
* - ``--profile``, ``-P``
75+
- string
76+
- Name of the profile where your credentials are saved. If omitted,
77+
uses the {+default-profile+}. To learn more about
78+
creating a profile, see :ref:`mcli-configure`.
79+
80+
You must have credentials with the :authrole:`Global Owner` role to
81+
delete a Global |api| Key.
82+
- no
83+
84+
.. _mcli-iam-global-apikey-delete-output:
85+
86+
Output
87+
------
88+
89+
If the command succeeds, it returns the following output. If the command returns errors, see :ref:`Troubleshooting
90+
<troubleshooting>` for recommended solutions.
91+
92+
.. code-block:: sh
93+
:copyable: false
94+
95+
? Are you sure you want to delete: <api-key-id> Yes
96+
API Key '<api-key-id>' deleted
97+
98+
.. _mcli-iam-global-apikey-delete-examples:
99+
100+
Example
101+
-------
102+
103+
The following command deletes the specified Global |api| Key with
104+
confirmation. The command uses the {+default-profile+}, which contains credentials for accessing the |onprem| instance.
105+
106+
.. code-block:: sh
107+
108+
mongocli iam globalApiKey delete 5f3d8790c9022019903c1234
109+
110+
The previous command prints the following to the terminal.
111+
112+
.. code-block:: sh
113+
:copyable: false
114+
115+
? Are you sure you want to delete: 5f3d8790c9022019903c1234 Yes
116+
API Key '5f3d8790c9022019903c1234' deleted

0 commit comments

Comments
 (0)